//----------------------------------------------------------------------------- // Copyright (c) 2011 - 2015 Advanced Micro Devices, Inc. All rights reserved. //----------------------------------------------------------------------------- /// @file amd_hsa_program.hpp /// @author AMD HSA Finalizer Team /// /// @brief Public AMD HSA Program Interfaces. #ifndef AMD_HSA_PROGRAM_HPP #define AMD_HSA_PROGRAM_HPP #include #include #include #include #include "amd_hsa_code.hpp" #include "Brig.h" #include "hsa.h" #include "hsa_ext_finalize.h" /// @brief Descriptive version of AMD HSA Program. #define AMD_HSA_PROGRAM_VERSION "AMD HSA Program v1.04 (August 3, 2015)" #define AMD_HSA_PROGRAM_VERSION_MAJOR 1 #define AMD_HSA_PROGRAM_VERSION_MINOR 4 /// @brief Environment variable. If set, overrides options parameter from /// Program::Create with contents of this environment variable. #define ENVVAR_AMD_HSA_PROGRAM_CREATE_OPTIONS "AMD_HSA_PROGRAM_CREATE_OPTIONS" /// @brief Environment variable. If set, concatenates options parameter from /// Program::Create with contents of this environment variable. #define ENVVAR_AMD_HSA_PROGRAM_CREATE_OPTIONS_APPEND "AMD_HSA_PROGRAM_CREATE_OPTIONS_APPEND" /// @brief Environment variable. If set, overrides options parameter from /// Program::Finalize with contents of this environment variable. #define ENVVAR_AMD_HSA_PROGRAM_FINALIZE_OPTIONS "AMD_HSA_PROGRAM_FINALIZE_OPTIONS" /// @brief Environment variable. If set, concatenates options parameter from /// Program::Finalize with contents of this environment variable. #define ENVVAR_AMD_HSA_PROGRAM_FINALIZE_OPTIONS_APPEND "AMD_HSA_PROGRAM_FINALIZE_OPTIONS_APPEND" /// @brief AMD HSA Program attributes (in addition to hsa_ext_program_info_t, /// which is defined in HSA Runtime Specification), enumeration values below /// must be negative. typedef int32_t amd_hsa_program_info32_t; enum amd_hsa_program_info_t { /// @brief Major version of BRIG specified when AMD HSA Program was created. /// The type of this attribute is BrigVersion32_t. AMD_HSA_PROGRAM_INFO_BRIG_VERSION_MAJOR = -1, /// @brief Minor version of BRIG specified when AMD HSA Program was created. /// The type of this attribute is BrigVersion32_t. AMD_HSA_PROGRAM_INFO_BRIG_VERSION_MINOR = -2, /// @brief Indicates whether or not AMD HSA Program was created with debugging /// enabled. The type of this attribute is bool. AMD_HSA_PROGRAM_INFO_IS_DEBUGGING_ENABLED = -3 }; namespace amd { namespace hsa { namespace program { /// @class Context class Context { public: /// @brief Default destructor. virtual ~Context() {} /// @brief Invoked when AMD HSA Program needs to allocate @p size bytes of /// code object memory whose alignment is specified by @p align. /// /// @param[in] size Requested allocation size in bytes. /// @param[in] align Requested alignment. /// /// @returns Pointer to allocated code object memory on success, null pointer /// on failure. virtual void* CodeObjectAlloc(size_t size, size_t align) = 0; /// @brief Invoked when AMD HSA Program needs to copy @p size bytes from /// memory pointed to by @p src to code object memory pointed to by @p dst. /// /// @param[in] dst Pointer to code object memory to copy to. /// @param[in] src Pointer to memory to copy from. /// @param[in] size Requested copy size in bytes. /// /// @returns True on success, false on failure. virtual bool CodeObjectCopy(void *dst, const void *src, size_t size) = 0; /// @brief Invoked when AMD HSA Program needs to deallocate @p size bytes of /// code object memory pointed to by @p ptr. /// /// @param[in] ptr Pointer to code object memory to deallocate. /// @param[in] size Requested deallocation size in bytes. virtual void CodeObjectFree(void *ptr, size_t size) = 0; /// @brief Invoked when AMD HSA Finalizer and Program needs to reprot message or error /// /// @param[in] str Message to report. virtual void ReportMessage(const std::string& str) = 0; protected: /// @brief Default constructor. Context() {} private: /// @brief Copy constructor - not available. Context(const Context&); /// @brief Assignment operator - not available. Context& operator=(const Context&); }; class Finalizer; /// @class Program class Program: public amd::hsa::common::Signed<0x71BB0A093D69DA92> { public: /// @brief Constant BRIG Module iterator. typedef std::vector::const_iterator const_module_iterator; /// @brief BRIG Module iterator. typedef std::vector::iterator module_iterator; /// @brief Invalid HSA Program Handle. static const uint64_t INVALID_HANDLE = 0; /// @brief Destructor. virtual ~Program() {} /// @brief Converts AMD HSA Program @p program_object to HSA Program Handle. /// /// @param[in] program_object AMD HSA Program to convert. Can be null. /// /// @returns HSA Program Handle on success, invalid handle on failure. static hsa_ext_program_t Handle(Program *program_object); /// @brief Converts HSA Program Handle @p program_handle to AMD HSA Program. /// /// @param[in] program_handle HSA Program Handle to convert. Can be invalid. /// /// @returns AMD HSA Program on success, null on failure. static Program* Object(hsa_ext_program_t program_handle); /// @returns Constant iterator to first BRIG Module in AMD HSA Program. If /// AMD HSA Program does not contain any BRIG Modules, returned constant /// iterator will be equal to Program::module_end(). virtual const_module_iterator module_begin() const = 0; /// @returns Constant iterator to entity following last BRIG Module in AMD /// HSA Program. virtual const_module_iterator module_end() const = 0; /// @returns Iterator to first BRIG Module in AMD HSA Program. If /// AMD HSA Program does not contain any BRIG Modules, returned /// iterator will be equal to Program::module_end(). virtual module_iterator module_begin() = 0; /// @returns Iterator to entity following last BRIG Module in AMD /// HSA Program. virtual module_iterator module_end() = 0; /// @returns Context associated with AMD HSA Program. virtual Context* GetContext() const = 0; /// @returns Finalizer associated with this AMD HSA Program. virtual Finalizer* GetFinalizer() const = 0; /// @brief Retrieves current value of specified AMD HSA Program's /// @p attribute. /// /// @param[in] attribute AMD HSA Program's attribute to retrieve. Can be /// invalid. /// @param[out] value Pointer to client-allocated memory to store attribute's /// value in. Must not be null. If client-allocated memory is not large enough /// to hold attribute's value, behaviour is undefined. /// /// @retval HSA_STATUS_SUCCESS Function executed successfully. /// @retval HSA_STATUS_ERROR_INVALID_ARGUMENT Specified @p attribute is /// invalid AMD HSA Program's attribute. /// /// @note If function failed to execute successfully, details of failure /// can be retrieved using Program::GetLog. virtual hsa_status_t GetInfo(amd_hsa_program_info32_t attribute, void *value) const = 0; /// @brief Adds specified BRIG Module @p module to AMD HSA Program. /// /// @details AMD HSA Program does not perform deep copy of BRIG Module /// upon addition, it stores pointer to BRIG Module. BRIG Module is owned by /// the client, which has to ensure that the lifetime of BRIG Module is /// greater than the lifetime of AMD HSA Program. /// /// @param[in] module BRIG Module to add. Must not be null. /// /// @retval HSA_STATUS_SUCCESS Function executed successfully. /// @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES Function failed to allocate /// resources. /// @retval HSA_EXT_STATUS_ERROR_INVALID_MODULE Specified @p module is invalid /// BRIG module. /// @retval HSA_EXT_STATUS_ERROR_MODULE_ALREADY_INCLUDED Specified @p module /// is already included in AMD HSA Program. /// @retval HSA_EXT_STATUS_ERROR_INCOMPATIBLE_MODULE Specified @p module is /// incompatible with AMD HSA Program. /// @retval HSA_EXT_STATUS_ERROR_SYMBOL_MISMATCH Symbol in specified @p module /// is incompatible with symbol in AMD HSA Program. /// /// @note If function failed to execute successfully, details of failure /// can be retrieved using Program::GetLog. virtual hsa_status_t AddModule(hsa_ext_module_t module) = 0; /// @brief Finalizes AMD HSA Program with specified @p target, /// @p call_convention, @p options, @p control_directives, and /// @p code_object_type. /// /// @details Finalizes all kernels and indirect functions that belong to /// AMD HSA Program for specified @p target, @p call_convention, /// @p options, @p control_directives, and @p code_object_type. Transitive /// closure of all functions specified by call or scall must be defined. /// All kernels and indirect functions that belong to AMD HSA Program must /// be defined. Kernels and indirect functions that are referenced in kernels /// and indirect functions that belong to AMD HSA Program may or may not be /// defined, but must be declared. All global and readonly variables that /// belong to AMD HSA Program, or referenced in kernels and indirect functions /// that belong to AMD HSA Program may or may not be defined, but must be /// declared. /// /// @param[in] target Target to finalize for. Must not be null. /// @param[in] call_convention Call convention to finalize for. Must be valid. /// @param[in] options Options to finalize for. Can be null. /// @param[in] control_directives Control directives to finalize for. Can be /// invalid. /// @param[in] code_object_type Code object type to create. Must be valid. /// @param[out] code_object Code object generated by AMD HSA Program. Must /// not be null. /// /// @retval HSA_STATUS_SUCCESS Function executed successfully. /// @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES Function failed to allocate /// resources. /// @retval HSA_STATUS_ERROR_INVALID_ISA Specified @p target is invalid. /// @retval HSA_EXT_STATUS_ERROR_DIRECTIVE_MISMATCH Specified /// @p control_directives does not match control directives in /// one of kernels or indirect functions that belong to AMD HSA Program. /// @retval HSA_EXT_STATUS_ERROR_FINALIZATION_FAILED AMD HSA Program failed /// to finalize. /// /// @note If function failed to execute successfully, details of failure /// can be retrieved using Program::GetLog. /// /// @deprecated @p control_directives will be included in @p options starting /// AMD HSA Program v2.0. virtual hsa_status_t Finalize( const char *target, int32_t call_convention, const char *options, hsa_ext_control_directives_t control_directives, hsa_code_object_type_t code_object_type, hsa_code_object_t *code_object) = 0; protected: /// @brief Default constructor. Program() {} private: /// @brief Copy constructor - not available. Program(const Program&); /// @brief Assignment operator - not available. Program& operator=(const Program&); }; /// @class Finalizer class Finalizer { public: /// @brief Destructor. virtual ~Finalizer() {} /// @brief Creates AMD HSA Finalizer with specified @p context. /// /// @param[in] context Context. Must not be null. /// /// @returns AMD HSA Finalizer on success, null on failure. static Finalizer* CreateFinalizer(Context* context); /// @brief Destroys AMD HSA Finalizer @p finalizer_object. /// /// @param[in] finalizer_object AMD HSA Finalizer to destroy. Must not be null. static void DestroyFinalizer(Finalizer *finalizer_object); /// @brief Creates empty AMD HSA Program with specified @p profile, /// @p machine_model, @p rounding_mode, @p options, @p context, @p major and /// @p minor BRIG versions. /// /// @param[in] profile HSA profile. Must be valid. /// @param[in] machine_model HSA machine model. Must be valid. /// @param[in] rounding_mode HSA rounding mode. Must be valid. /// @param[in] options User options. Can be null. /// @param[in] brig_major Major BRIG version. Must be valid. /// @param[in] brig_minor Minor BRIG version. Must be valid. /// /// @returns AMD HSA Program on success, null on failure. virtual Program* CreateProgram( hsa_profile_t profile, hsa_machine_model_t machine_model, hsa_default_float_rounding_mode_t rounding_mode, const char *options, BrigVersion32_t brig_major = BRIG_VERSION_BRIG_MAJOR, BrigVersion32_t brig_minor = BRIG_VERSION_BRIG_MINOR) = 0; /// @brief Destroys AMD HSA Program @p program_object. /// /// @param[in] program_object AMD HSA Program to destroy. Must not be null. virtual void DestroyProgram(Program *program_object) = 0; /// @brief Prints available finalizer options as error and exits. virtual void PrintFinalizerOptions() const = 0; /// @returns Context associated with Finalizer. virtual Context* GetContext() const = 0; /// @brief Enables code cache optimization. virtual void EnableCodeCache() = 0; /// @brief Disables code cache optimization. virtual void DisableCodeCache() = 0; /// @returns True if code cache is enabled, false otherwise. virtual bool IsCodeCacheEnabled() const = 0; /// @returns List of names for supported targets. virtual const std::vector& GetSupportedTargets() const = 0; protected: /// @brief Default constructor. Finalizer() {} private: /// @brief Copy constructor - not available. Finalizer(const Finalizer&); /// @brief Assignment operator - not available. Finalizer& operator=(const Finalizer&); }; } // namespace program } // namespace hsa } // namespace amd #endif // AMD_HSA_PROGRAM_HPP