ROCr API Documentation¶
Runtime Notification¶
-
enum
hsa_status_t
¶ Status codes.
Values:
-
enumerator
HSA_STATUS_SUCCESS
¶ The function has been executed successfully.
-
enumerator
HSA_STATUS_INFO_BREAK
¶ A traversal over a list of elements has been interrupted by the application before completing.
-
enumerator
HSA_STATUS_ERROR
¶ A generic error has occurred.
-
enumerator
HSA_STATUS_ERROR_INVALID_ARGUMENT
¶ One of the actual arguments does not meet a precondition stated in the documentation of the corresponding formal argument.
-
enumerator
HSA_STATUS_ERROR_INVALID_QUEUE_CREATION
¶ The requested queue creation is not valid.
-
enumerator
HSA_STATUS_ERROR_INVALID_ALLOCATION
¶ The requested allocation is not valid.
-
enumerator
HSA_STATUS_ERROR_INVALID_AGENT
¶ The agent is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_REGION
¶ The memory region is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_SIGNAL
¶ The signal is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_QUEUE
¶ The queue is invalid.
-
enumerator
HSA_STATUS_ERROR_OUT_OF_RESOURCES
¶ The HSA runtime failed to allocate the necessary resources. This error may also occur when the HSA runtime needs to spawn threads or create internal OS-specific events.
-
enumerator
HSA_STATUS_ERROR_INVALID_PACKET_FORMAT
¶ The AQL packet is malformed.
-
enumerator
HSA_STATUS_ERROR_RESOURCE_FREE
¶ An error has been detected while releasing a resource.
-
enumerator
HSA_STATUS_ERROR_NOT_INITIALIZED
¶ An API other than hsa_init has been invoked while the reference count of the HSA runtime is 0.
-
enumerator
HSA_STATUS_ERROR_REFCOUNT_OVERFLOW
¶ The maximum reference count for the object has been reached.
-
enumerator
HSA_STATUS_ERROR_INCOMPATIBLE_ARGUMENTS
¶ The arguments passed to a functions are not compatible.
-
enumerator
HSA_STATUS_ERROR_INVALID_INDEX
¶ The index is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_ISA
¶ The instruction set architecture is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_ISA_NAME
¶ The instruction set architecture name is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_CODE_OBJECT
¶ The code object is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_EXECUTABLE
¶ The executable is invalid.
-
enumerator
HSA_STATUS_ERROR_FROZEN_EXECUTABLE
¶ The executable is frozen.
-
enumerator
HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
¶ There is no symbol with the given name.
-
enumerator
HSA_STATUS_ERROR_VARIABLE_ALREADY_DEFINED
¶ The variable is already defined.
-
enumerator
HSA_STATUS_ERROR_VARIABLE_UNDEFINED
¶ The variable is undefined.
-
enumerator
HSA_STATUS_ERROR_EXCEPTION
¶ An HSAIL operation resulted in a hardware exception.
-
enumerator
HSA_STATUS_ERROR_INVALID_CODE_SYMBOL
¶ The code object symbol is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_EXECUTABLE_SYMBOL
¶ The executable symbol is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_FILE
¶ The file descriptor is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_CODE_OBJECT_READER
¶ The code object reader is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_CACHE
¶ The cache is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_WAVEFRONT
¶ The wavefront is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_SIGNAL_GROUP
¶ The signal group is invalid.
-
enumerator
HSA_STATUS_ERROR_INVALID_RUNTIME_STATE
¶ The HSA runtime is not in the configuration state.
-
enumerator
HSA_STATUS_ERROR_FATAL
¶ The queue received an error that may require process termination.
-
enumerator
-
hsa_status_t HSA_API hsa_status_string (hsa_status_t status, const char **status_string)
Query additional information about a status code.
- Parameters
[in] status
: Status code.[out] status_string
: A NUL-terminated string that describes the error status.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:status
is an invalid status code, orstatus_string
is NULL.
common definition¶
-
enum
hsa_access_permission_t
¶ Access permissions.
Values:
-
enumerator
HSA_ACCESS_PERMISSION_RO
¶ Read-only access.
-
enumerator
HSA_ACCESS_PERMISSION_WO
¶ Write-only access.
-
enumerator
HSA_ACCESS_PERMISSION_RW
¶ Read and write access.
-
enumerator
-
struct
hsa_dim3_t
¶ Three-dimensional coordinate.
Initialization and Shut Down¶
-
hsa_status_t HSA_API hsa_init ()
Initialize the HSA runtime.
Initializes the HSA runtime if it is not already initialized, and increases the reference counter associated with the HSA runtime for the current process. Invocation of any HSA function other than hsa_init results in undefined behavior if the current HSA runtime reference counter is less than one.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_REFCOUNT_OVERFLOW
: The HSA runtime reference count reaches INT32_MAX.
-
hsa_status_t HSA_API hsa_shut_down ()
Shut down the HSA runtime.
Decreases the reference count of the HSA runtime instance. When the reference count reaches 0, the HSA runtime is no longer considered valid but the application might call hsa_init to initialize the HSA runtime again.
Once the reference count of the HSA runtime reaches 0, all the resources associated with it (queues, signals, agent information, etc.) are considered invalid and any attempt to reference them in subsequent API calls results in undefined behavior. When the reference count reaches 0, the HSA runtime may release resources associated with it.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.
System and Agent Information¶
-
enum
hsa_agent_feature_t
¶ Agent features.
Values:
-
enumerator
HSA_AGENT_FEATURE_KERNEL_DISPATCH
¶ The agent supports AQL packets of kernel dispatch type. If this feature is enabled, the agent is also a kernel agent.
-
enumerator
HSA_AGENT_FEATURE_AGENT_DISPATCH
¶ The agent supports AQL packets of agent dispatch type.
-
enumerator
-
enum
hsa_agent_info_t
¶ Agent attributes.
Values:
-
enumerator
HSA_AGENT_INFO_NAME
¶ Agent name. The type of this attribute is a NUL-terminated char[64]. The name must be at most 63 characters long (not including the NUL terminator) and all array elements not used for the name must be NUL.
-
enumerator
HSA_AGENT_INFO_VENDOR_NAME
¶ Name of vendor. The type of this attribute is a NUL-terminated char[64]. The name must be at most 63 characters long (not including the NUL terminator) and all array elements not used for the name must be NUL.
-
enumerator
HSA_AGENT_INFO_FEATURE
¶ Agent capability. The type of this attribute is hsa_agent_feature_t.
-
enumerator
HSA_AGENT_INFO_MACHINE_MODEL
¶ - Deprecated:
Query HSA_ISA_INFO_MACHINE_MODELS for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Machine model supported by the agent. The type of this attribute is hsa_machine_model_t.
-
enumerator
HSA_AGENT_INFO_PROFILE
¶ - Deprecated:
Query HSA_ISA_INFO_PROFILES for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Profile supported by the agent. The type of this attribute is hsa_profile_t.
-
enumerator
HSA_AGENT_INFO_DEFAULT_FLOAT_ROUNDING_MODE
¶ - Deprecated:
Query HSA_ISA_INFO_DEFAULT_FLOAT_ROUNDING_MODES for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Default floating-point rounding mode. The type of this attribute is hsa_default_float_rounding_mode_t, but the value HSA_DEFAULT_FLOAT_ROUNDING_MODE_DEFAULT is not allowed.
-
enumerator
HSA_AGENT_INFO_BASE_PROFILE_DEFAULT_FLOAT_ROUNDING_MODES
¶ - Deprecated:
Query HSA_ISA_INFO_BASE_PROFILE_DEFAULT_FLOAT_ROUNDING_MODES for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
A bit-mask of hsa_default_float_rounding_mode_t values, representing the default floating-point rounding modes supported by the agent in the Base profile. The type of this attribute is uint32_t. The default floating-point rounding mode (HSA_AGENT_INFO_DEFAULT_FLOAT_ROUNDING_MODE) bit must not be set.
-
enumerator
HSA_AGENT_INFO_FAST_F16_OPERATION
¶ - Deprecated:
Query HSA_ISA_INFO_FAST_F16_OPERATION for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Flag indicating that the f16 HSAIL operation is at least as fast as the f32 operation in the current agent. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is bool.
-
enumerator
HSA_AGENT_INFO_WAVEFRONT_SIZE
¶ - Deprecated:
Query HSA_WAVEFRONT_INFO_SIZE for a given wavefront and intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas and the first wavefront enumerated by hsa_isa_iterate_wavefronts for that ISA.
Number of work-items in a wavefront. Must be a power of 2 in the range [1,256]. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_WORKGROUP_MAX_DIM
¶ - Deprecated:
Query HSA_ISA_INFO_WORKGROUP_MAX_DIM for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Maximum number of work-items of each dimension of a work-group. Each maximum must be greater than 0. No maximum can exceed the value of HSA_AGENT_INFO_WORKGROUP_MAX_SIZE. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is uint16_t[3].
-
enumerator
HSA_AGENT_INFO_WORKGROUP_MAX_SIZE
¶ - Deprecated:
Query HSA_ISA_INFO_WORKGROUP_MAX_SIZE for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Maximum total number of work-items in a work-group. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_GRID_MAX_DIM
¶ - Deprecated:
Query HSA_ISA_INFO_GRID_MAX_DIM for a given intruction set architecture supported by the agent instead.
Maximum number of work-items of each dimension of a grid. Each maximum must be greater than 0, and must not be smaller than the corresponding value in HSA_AGENT_INFO_WORKGROUP_MAX_DIM. No maximum can exceed the value of HSA_AGENT_INFO_GRID_MAX_SIZE. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is hsa_dim3_t.
-
enumerator
HSA_AGENT_INFO_GRID_MAX_SIZE
¶ - Deprecated:
Query HSA_ISA_INFO_GRID_MAX_SIZE for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Maximum total number of work-items in a grid. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_FBARRIER_MAX_SIZE
¶ - Deprecated:
Query HSA_ISA_INFO_FBARRIER_MAX_SIZE for a given intruction set architecture supported by the agent instead. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Maximum number of fbarriers per work-group. Must be at least 32. The value of this attribute is undefined if the agent is not a kernel agent. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_QUEUES_MAX
¶ - Deprecated:
The maximum number of queues is not statically determined.
Maximum number of queues that can be active (created but not destroyed) at one time in the agent. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_QUEUE_MIN_SIZE
¶ Minimum number of packets that a queue created in the agent can hold. Must be a power of 2 greater than 0. Must not exceed the value of HSA_AGENT_INFO_QUEUE_MAX_SIZE. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_QUEUE_MAX_SIZE
¶ Maximum number of packets that a queue created in the agent can hold. Must be a power of 2 greater than 0. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_QUEUE_TYPE
¶ Type of a queue created in the agent. The type of this attribute is hsa_queue_type32_t.
-
enumerator
HSA_AGENT_INFO_NODE
¶ - Deprecated:
NUMA information is not exposed anywhere else in the API.
Identifier of the NUMA node associated with the agent. The type of this attribute is uint32_t.
-
enumerator
HSA_AGENT_INFO_DEVICE
¶ Type of hardware device associated with the agent. The type of this attribute is hsa_device_type_t.
-
enumerator
HSA_AGENT_INFO_CACHE_SIZE
¶ - Deprecated:
Query hsa_agent_iterate_caches to retrieve information about the caches present in a given agent.
Array of data cache sizes (L1..L4). Each size is expressed in bytes. A size of 0 for a particular level indicates that there is no cache information for that level. The type of this attribute is uint32_t[4].
-
enumerator
HSA_AGENT_INFO_ISA
¶ - Deprecated:
An agent may support multiple instruction set architectures. See hsa_agent_iterate_isas. If more than one ISA is supported by the agent, the returned value corresponds to the first ISA enumerated by hsa_agent_iterate_isas.
Instruction set architecture of the agent. The type of this attribute is hsa_isa_t.
-
enumerator
HSA_AGENT_INFO_EXTENSIONS
¶ Bit-mask indicating which extensions are supported by the agent. An extension with an ID of
i
is supported if the bit at positioni
is set. The type of this attribute is uint8_t[128].
-
enumerator
HSA_AGENT_INFO_VERSION_MAJOR
¶ Major version of the HSA runtime specification supported by the agent. The type of this attribute is uint16_t.
-
enumerator
HSA_AGENT_INFO_VERSION_MINOR
¶ Minor version of the HSA runtime specification supported by the agent. The type of this attribute is uint16_t.
-
enumerator
-
enum
hsa_cache_info_t
¶ Cache attributes.
Values:
-
enumerator
HSA_CACHE_INFO_NAME_LENGTH
¶ The length of the cache name in bytes, not including the NUL terminator. The type of this attribute is uint32_t.
-
enumerator
HSA_CACHE_INFO_NAME
¶ Human-readable description. The type of this attribute is a NUL-terminated character array with the length equal to the value of HSA_CACHE_INFO_NAME_LENGTH attribute.
-
enumerator
HSA_CACHE_INFO_LEVEL
¶ Cache level. A L1 cache must return a value of 1, a L2 must return a value of 2, and so on. The type of this attribute is uint8_t.
-
enumerator
HSA_CACHE_INFO_SIZE
¶ Cache size, in bytes. A value of 0 indicates that there is no size information available. The type of this attribute is uint32_t.
-
enumerator
-
enum
hsa_default_float_rounding_mode_t
¶ Default floating-point rounding mode.
Values:
-
enumerator
HSA_DEFAULT_FLOAT_ROUNDING_MODE_DEFAULT
¶ Use a default floating-point rounding mode specified elsewhere.
-
enumerator
HSA_DEFAULT_FLOAT_ROUNDING_MODE_ZERO
¶ Operations that specify the default floating-point mode are rounded to zero by default.
-
enumerator
HSA_DEFAULT_FLOAT_ROUNDING_MODE_NEAR
¶ Operations that specify the default floating-point mode are rounded to the nearest representable number and that ties should be broken by selecting the value with an even least significant bit.
-
enumerator
-
enum
hsa_device_type_t
¶ Hardware device type.
Values:
-
enumerator
HSA_DEVICE_TYPE_CPU
¶ CPU device.
-
enumerator
HSA_DEVICE_TYPE_GPU
¶ GPU device.
-
enumerator
HSA_DEVICE_TYPE_DSP
¶ DSP device.
-
enumerator
-
enum
hsa_endianness_t
¶ Endianness. A convention used to interpret the bytes making up a data word.
Values:
-
enumerator
HSA_ENDIANNESS_LITTLE
¶ The least significant byte is stored in the smallest address.
-
enumerator
HSA_ENDIANNESS_BIG
¶ The most significant byte is stored in the smallest address.
-
enumerator
-
enum
hsa_exception_policy_t
¶ Exception policies applied in the presence of hardware exceptions.
Values:
-
enumerator
HSA_EXCEPTION_POLICY_BREAK
¶ If a hardware exception is detected, a work-item signals an exception.
-
enumerator
HSA_EXCEPTION_POLICY_DETECT
¶ If a hardware exception is detected, a hardware status bit is set.
-
enumerator
-
enum
hsa_extension_t
¶ HSA extensions.
Values:
-
enumerator
HSA_EXTENSION_FINALIZER
¶ Finalizer extension.
-
enumerator
HSA_EXTENSION_IMAGES
¶ Images extension.
-
enumerator
HSA_EXTENSION_PERFORMANCE_COUNTERS
¶ Performance counter extension.
-
enumerator
HSA_EXTENSION_PROFILING_EVENTS
¶ Profiling events extension.
-
enumerator
HSA_EXTENSION_STD_LAST
¶ Extension count.
-
enumerator
HSA_AMD_FIRST_EXTENSION
¶ First AMD extension number.
-
enumerator
HSA_EXTENSION_AMD_PROFILER
¶ Profiler extension.
-
enumerator
HSA_EXTENSION_AMD_LOADER
¶ Loader extension.
-
enumerator
HSA_EXTENSION_AMD_AQLPROFILE
¶ AqlProfile extension.
-
enumerator
HSA_AMD_LAST_EXTENSION
¶ Last AMD extension.
-
enumerator
-
enum
hsa_machine_model_t
¶ Machine model. A machine model determines the size of certain data types in HSA runtime and an agent.
Values:
-
enumerator
HSA_MACHINE_MODEL_SMALL
¶ Small machine model. Addresses use 32 bits.
-
enumerator
HSA_MACHINE_MODEL_LARGE
¶ Large machine model. Addresses use 64 bits.
-
enumerator
-
enum
hsa_profile_t
¶ Profile. A profile indicates a particular level of feature support. For example, in the base profile the application must use the HSA runtime allocator to reserve shared virtual memory, while in the full profile any host pointer can be shared across all the agents.
Values:
-
enumerator
HSA_PROFILE_BASE
¶ Base profile.
-
enumerator
HSA_PROFILE_FULL
¶ Full profile.
-
enumerator
-
enum
hsa_system_info_t
¶ System attributes.
Values:
-
enumerator
HSA_SYSTEM_INFO_VERSION_MAJOR
¶ Major version of the HSA runtime specification supported by the implementation. The type of this attribute is uint16_t.
-
enumerator
HSA_SYSTEM_INFO_VERSION_MINOR
¶ Minor version of the HSA runtime specification supported by the implementation. The type of this attribute is uint16_t.
-
enumerator
HSA_SYSTEM_INFO_TIMESTAMP
¶ Current timestamp. The value of this attribute monotonically increases at a constant rate. The type of this attribute is uint64_t.
-
enumerator
HSA_SYSTEM_INFO_TIMESTAMP_FREQUENCY
¶ Timestamp value increase rate, in Hz. The timestamp (clock) frequency is in the range 1-400MHz. The type of this attribute is uint64_t.
-
enumerator
HSA_SYSTEM_INFO_SIGNAL_MAX_WAIT
¶ Maximum duration of a signal wait operation. Expressed as a count based on the timestamp frequency. The type of this attribute is uint64_t.
-
enumerator
HSA_SYSTEM_INFO_ENDIANNESS
¶ Endianness of the system. The type of this attribute is hsa_endianness_t.
-
enumerator
HSA_SYSTEM_INFO_MACHINE_MODEL
¶ Machine model supported by the HSA runtime. The type of this attribute is hsa_machine_model_t.
-
enumerator
HSA_SYSTEM_INFO_EXTENSIONS
¶ Bit-mask indicating which extensions are supported by the implementation. An extension with an ID of
i
is supported if the bit at positioni
is set. The type of this attribute is uint8_t[128].
-
enumerator
HSA_AMD_SYSTEM_INFO_BUILD_VERSION
¶ String containing the ROCr build identifier.
-
enumerator
-
hsa_status_t HSA_API hsa_agent_get_info (hsa_agent_t agent, hsa_agent_info_t attribute, void *value)
Get the current value of an attribute for a given agent.
- Parameters
[in] agent
: A valid agent.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid agent attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_agent_iterate_caches (hsa_agent_t agent, hsa_status_t(*callback)(hsa_cache_t cache, void *data), void *data)
Iterate over the memory caches of a given agent, and invoke an application-defined callback on every iteration.
Caches are visited in ascending order according to the value of the HSA_CACHE_INFO_LEVEL attribute.
- Parameters
[in] agent
: A valid agent.[in] callback
: Callback to be invoked once per cache that is present in the agent. The HSA runtime passes two arguments to the callback: the cache and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and that value is returned.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API hsa_agent_major_extension_supported (uint16_t extension, hsa_agent_t agent, uint16_t version_major, uint16_t *version_minor, bool *result)
Query if a given version of an extension is supported by an agent. All minor versions from 0 up to the returned
version_minor
must be supported.- Parameters
[in] extension
: Extension identifier.[in] agent
: Agent.[in] version_major
: Major version number.[out] version_minor
: Minor version number.[out] result
: Pointer to a memory location where the HSA runtime stores the result of the check. The result is true if the specified version of the extension is supported, and false otherwise. The result must be false if hsa_system_extension_supported returns false for the same extension version.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:extension
is not a valid extension, orversion_minor
is NULL, orresult
is NULL.
-
hsa_status_t HSA_API hsa_cache_get_info (hsa_cache_t cache, hsa_cache_info_t attribute, void *value)
Get the current value of an attribute for a given cache object.
- Parameters
[in] cache
: Cache.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CACHE
: The cache is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid instruction set architecture attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_extension_get_name (uint16_t extension, const char **name)
Query the name of a given extension.
- Parameters
[in] extension
: Extension identifier. If the extension is not supported by the implementation (see HSA_SYSTEM_INFO_EXTENSIONS), the behavior is undefined.[out] name
: Pointer to a memory location where the HSA runtime stores the extension name. The extension name is a NUL-terminated string.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:extension
is not a valid extension, orname
is NULL.
-
hsa_status_t HSA_API hsa_iterate_agents (hsa_status_t(*callback)(hsa_agent_t agent, void *data), void *data)
Iterate over the available agents, and invoke an application-defined callback on every iteration.
- Parameters
[in] callback
: Callback to be invoked once per agent. The HSA runtime passes two arguments to the callback: the agent and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_iterate_agents returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_system_extension_supported (uint16_t extension, uint16_t version_major, uint16_t version_minor, bool *result)
Query if a given version of an extension is supported by the HSA implementation.
- Deprecated:
- Parameters
[in] extension
: Extension identifier.[in] version_major
: Major version number.[in] version_minor
: Minor version number.[out] result
: Pointer to a memory location where the HSA runtime stores the result of the check. The result is true if the specified version of the extension is supported, and false otherwise.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:extension
is not a valid extension, orresult
is NULL.
-
hsa_status_t HSA_API hsa_system_get_info (hsa_system_info_t attribute, void *value)
Get the current value of a system attribute.
- Parameters
[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid system attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_system_get_major_extension_table (uint16_t extension, uint16_t version_major, size_t table_length, void *table)
Retrieve the function pointers corresponding to a given major version of an extension. Portable applications are expected to invoke the extension API using the returned function pointers.
The application is responsible for verifying that the given major version of the extension is supported by the HSA implementation (see hsa_system_major_extension_supported). If the given combination of extension and major version is not supported by the implementation, the behavior is undefined. Additionally if the length doesn’t allow space for a full minor version, it is implementation defined if only some of the function pointers for that minor version get written.
- Parameters
[in] extension
: Extension identifier.[in] version_major
: Major version number for which to retrieve the function pointer table.[in] table_length
: Size in bytes of the function pointer table to be populated. The implementation will not write more than this many bytes to the table.[out] table
: Pointer to an application-allocated function pointer table that is populated by the HSA runtime. Must not be NULL. The memory associated with table can be reused or freed after the function returns.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:extension
is not a valid extension, ortable
is NULL.
-
hsa_status_t HSA_API hsa_system_major_extension_supported (uint16_t extension, uint16_t version_major, uint16_t *version_minor, bool *result)
Query if a given version of an extension is supported by the HSA implementation. All minor versions from 0 up to the returned
version_minor
must be supported by the implementation.- Parameters
[in] extension
: Extension identifier.[in] version_major
: Major version number.[out] version_minor
: Minor version number.[out] result
: Pointer to a memory location where the HSA runtime stores the result of the check. The result is true if the specified version of the extension is supported, and false otherwise.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
:extension
is not a valid extension, orversion_minor
is NULL, orresult
is NULL.
Signals¶
-
struct
hsa_signal_t
¶ Signal handle.
-
typedef int32_t
hsa_signal_value_t
¶ Signal value. The value occupies 32 bits in small machine mode, and 64 bits in large machine mode.
-
struct
hsa_signal_group_t
¶ Group of signals.
-
enum
hsa_signal_condition_t
¶ Wait condition operator.
Values:
-
enumerator
HSA_SIGNAL_CONDITION_EQ
¶ The two operands are equal.
-
enumerator
HSA_SIGNAL_CONDITION_NE
¶ The two operands are not equal.
-
enumerator
HSA_SIGNAL_CONDITION_LT
¶ The first operand is less than the second operand.
-
enumerator
HSA_SIGNAL_CONDITION_GTE
¶ The first operand is greater than or equal to the second operand.
-
enumerator
-
enum
hsa_wait_state_t
¶ State of the application thread during a signal wait.
Values:
-
enumerator
HSA_WAIT_STATE_BLOCKED
¶ The application thread may be rescheduled while waiting on the signal.
-
enumerator
HSA_WAIT_STATE_ACTIVE
¶ The application thread stays active while waiting on a signal.
-
enumerator
-
void HSA_API hsa_signal_add_relaxed (hsa_signal_t signal, hsa_signal_value_t value)
Atomically increment the value of a signal by a given amount.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to add to the value of the signal.
-
void HSA_API HSA_DEPRECATED hsa_signal_add_release (hsa_signal_t signal, hsa_signal_value_t value)
Atomically increment the value of a signal by a given amount.
- Deprecated:
Renamed as hsa_signal_add_screlease.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to add to the value of the signal.
-
void HSA_API hsa_signal_add_scacq_screl (hsa_signal_t signal, hsa_signal_value_t value)
Atomically increment the value of a signal by a given amount.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to add to the value of the signal.
-
void HSA_API hsa_signal_add_scacquire (hsa_signal_t signal, hsa_signal_value_t value)
Atomically increment the value of a signal by a given amount.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to add to the value of the signal.
-
void HSA_API hsa_signal_add_screlease (hsa_signal_t signal, hsa_signal_value_t value)
Atomically increment the value of a signal by a given amount.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to add to the value of the signal.
-
void HSA_API HSA_DEPRECATED hsa_signal_and_acq_rel (hsa_signal_t signal, hsa_signal_value_t value)
Atomically perform a bitwise AND operation between the value of a signal and a given value.
- Deprecated:
Renamed as hsa_signal_and_scacq_screl.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to AND with the value of the signal.
-
void HSA_API hsa_signal_and_relaxed (hsa_signal_t signal, hsa_signal_value_t value)
Atomically perform a bitwise AND operation between the value of a signal and a given value.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to AND with the value of the signal.
-
void HSA_API hsa_signal_and_scacq_screl (hsa_signal_t signal, hsa_signal_value_t value)
Atomically perform a bitwise AND operation between the value of a signal and a given value.
If the value of the signal is changed, all the agents waiting on
signal
for whichvalue
satisfies their wait condition are awakened.- Parameters
[in] signal
: Signal. Ifsignal
is a queue doorbell signal, the behavior is undefined.[in] value
: Value to AND with the value of the signal.
Memory¶
-
enum
hsa_region_global_flag_t
¶ Global region flags.
Values:
-
enumerator
HSA_REGION_GLOBAL_FLAG_KERNARG
¶ The application can use memory in the region to store kernel arguments, and provide the values for the kernarg segment of a kernel dispatch. If this flag is set, then HSA_REGION_GLOBAL_FLAG_FINE_GRAINED must be set.
-
enumerator
HSA_REGION_GLOBAL_FLAG_FINE_GRAINED
¶ Updates to memory in this region are immediately visible to all the agents under the terms of the HSA memory model. If this flag is set, then HSA_REGION_GLOBAL_FLAG_COARSE_GRAINED must not be set.
-
enumerator
HSA_REGION_GLOBAL_FLAG_COARSE_GRAINED
¶ Updates to memory in this region can be performed by a single agent at a time. If a different agent in the system is allowed to access the region, the application must explicitely invoke hsa_memory_assign_agent in order to transfer ownership to that agent for a particular buffer.
-
enumerator
-
enum
hsa_region_info_t
¶ Attributes of a memory region.
Values:
-
enumerator
HSA_REGION_INFO_SEGMENT
¶ Segment where memory in the region can be used. The type of this attribute is hsa_region_segment_t.
-
enumerator
HSA_REGION_INFO_GLOBAL_FLAGS
¶ Flag mask. The value of this attribute is undefined if the value of HSA_REGION_INFO_SEGMENT is not HSA_REGION_SEGMENT_GLOBAL. The type of this attribute is uint32_t, a bit-field of hsa_region_global_flag_t values.
-
enumerator
HSA_REGION_INFO_SIZE
¶ Size of this region, in bytes. The type of this attribute is size_t.
-
enumerator
HSA_REGION_INFO_ALLOC_MAX_SIZE
¶ Maximum allocation size in this region, in bytes. Must not exceed the value of HSA_REGION_INFO_SIZE. The type of this attribute is size_t.
If the region is in the global or readonly segments, this is the maximum size that the application can pass to hsa_memory_allocate.
If the region is in the group segment, this is the maximum size (per work-group) that can be requested for a given kernel dispatch. If the region is in the private segment, this is the maximum size (per work-item) that can be requested for a specific kernel dispatch, and must be at least 256 bytes.
-
enumerator
HSA_REGION_INFO_ALLOC_MAX_PRIVATE_WORKGROUP_SIZE
¶ Maximum size (per work-group) of private memory that can be requested for a specific kernel dispatch. Must be at least 65536 bytes. The type of this attribute is uint32_t. The value of this attribute is undefined if the region is not in the private segment.
-
enumerator
HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED
¶ Indicates whether memory in this region can be allocated using hsa_memory_allocate. The type of this attribute is bool.
The value of this flag is always false for regions in the group and private segments.
-
enumerator
HSA_REGION_INFO_RUNTIME_ALLOC_GRANULE
¶ Allocation granularity of buffers allocated by hsa_memory_allocate in this region. The size of a buffer allocated in this region is a multiple of the value of this attribute. The value of this attribute is only defined if HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED is true for this region. The type of this attribute is size_t.
-
enumerator
HSA_REGION_INFO_RUNTIME_ALLOC_ALIGNMENT
¶ Alignment of buffers allocated by hsa_memory_allocate in this region. The value of this attribute is only defined if HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED is true for this region, and must be a power of 2. The type of this attribute is size_t.
-
enumerator
-
enum
hsa_region_segment_t
¶ Memory segments associated with a region.
Values:
-
enumerator
HSA_REGION_SEGMENT_GLOBAL
¶ Global segment. Used to hold data that is shared by all agents.
-
enumerator
HSA_REGION_SEGMENT_READONLY
¶ Read-only segment. Used to hold data that remains constant during the execution of a kernel.
-
enumerator
HSA_REGION_SEGMENT_PRIVATE
¶ Private segment. Used to hold data that is local to a single work-item.
-
enumerator
HSA_REGION_SEGMENT_GROUP
¶ Group segment. Used to hold data that is shared by the work-items of a work-group.
-
enumerator
HSA_REGION_SEGMENT_KERNARG
¶ Kernarg segment. Used to store kernel arguments.
-
enumerator
-
hsa_status_t HSA_API hsa_agent_iterate_regions (hsa_agent_t agent, hsa_status_t(*callback)(hsa_region_t region, void *data), void *data)
Iterate over the memory regions associated with a given agent, and invoke an application-defined callback on every iteration.
- Parameters
[in] agent
: A valid agent.[in] callback
: Callback to be invoked once per region that is accessible from the agent. The HSA runtime passes two arguments to the callback, the region and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_agent_iterate_regions returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API hsa_memory_allocate (hsa_region_t region, size_t size, void **ptr)
Allocate a block of memory in a given region.
- Parameters
[in] region
: Region where to allocate memory from. The region must have the HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED flag set.[in] size
: Allocation size, in bytes. Must not be zero. This value is rounded up to the nearest multiple of HSA_REGION_INFO_RUNTIME_ALLOC_GRANULE inregion
.[out] ptr
: Pointer to the location where to store the base address of the allocated block. The returned base address is aligned to the value of HSA_REGION_INFO_RUNTIME_ALLOC_ALIGNMENT inregion
. If the allocation fails, the returned value is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_REGION
: The region is invalid.HSA_STATUS_ERROR_INVALID_ALLOCATION
: The host is not allowed to allocate memory inregion
, orsize
is greater than the value of HSA_REGION_INFO_ALLOC_MAX_SIZE inregion
.HSA_STATUS_ERROR_INVALID_ARGUMENT
:ptr
is NULL, orsize
is 0.
-
hsa_status_t HSA_API hsa_memory_assign_agent (void *ptr, hsa_agent_t agent, hsa_access_permission_t access)
Change the ownership of a global, coarse-grained buffer.
The contents of a coarse-grained buffer are visible to an agent only after ownership has been explicitely transferred to that agent. Once the operation completes, the previous owner cannot longer access the data in the buffer.
An implementation of the HSA runtime is allowed, but not required, to change the physical location of the buffer when ownership is transferred to a different agent. In general the application must not assume this behavior. The virtual location (address) of the passed buffer is never modified.
- Parameters
[in] ptr
: Base address of a global buffer. The pointer must match an address previously returned by hsa_memory_allocate. The size of the buffer affected by the ownership change is identical to the size of that previous allocation. Ifptr
points to a fine-grained global buffer, no operation is performed and the function returns success. Ifptr
does not point to global memory, the behavior is undefined.[in] agent
: Agent that becomes the owner of the buffer. The application is responsible for ensuring thatagent
has access to the region that contains the buffer. It is allowed to change ownership to an agent that is already the owner of the buffer, with the same or different access permissions.[in] access
: Access permissions requested for the new owner.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:ptr
is NULL, oraccess
is not a valid access value.
-
hsa_status_t HSA_API hsa_memory_copy (void *dst, const void *src, size_t size)
Copy a block of memory from the location pointed to by
src
to the memory block pointed to bydst
.- Parameters
[out] dst
: Buffer where the content is to be copied. Ifdst
is in coarse-grained memory, the copied data is only visible to the agent currently assigned (hsa_memory_assign_agent) todst
.[in] src
: A valid pointer to the source of data to be copied. The source buffer must not overlap with the destination buffer. If the source buffer is in coarse-grained memory then it must be assigned to an agent, from which the data will be retrieved.[in] size
: Number of bytes to copy. Ifsize
is 0, no copy is performed and the function returns success. Copying a number of bytes larger than the size of the buffers pointed bydst
orsrc
results in undefined behavior.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ARGUMENT
: The source or destination pointers are NULL.
-
hsa_status_t HSA_API hsa_memory_deregister (void *ptr, size_t size)
Deregister memory previously registered using hsa_memory_register.
If the memory interval being deregistered does not match a previous registration (start and end addresses), the behavior is undefined.
- Parameters
[in] ptr
: A pointer to the base of the buffer to be deregistered. If a NULL pointer is passed, no operation is performed.[in] size
: Size of the buffer to be deregistered.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.
-
hsa_status_t HSA_API hsa_memory_free (void *ptr)
Deallocate a block of memory previously allocated using hsa_memory_allocate.
- Parameters
[in] ptr
: Pointer to a memory block. Ifptr
does not match a value previously returned by hsa_memory_allocate, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.
-
hsa_status_t HSA_API hsa_memory_register (void *ptr, size_t size)
Register a global, fine-grained buffer.
Registering a buffer serves as an indication to the HSA runtime that the memory might be accessed from a kernel agent other than the host. Registration is a performance hint that allows the HSA runtime implementation to know which buffers will be accessed by some of the kernel agents ahead of time.
Registration is only recommended for buffers in the global segment that have not been allocated using the HSA allocator (hsa_memory_allocate), but an OS allocator instead. Registering an OS-allocated buffer in the base profile is equivalent to a no-op.
Registrations should not overlap.
- Parameters
[in] ptr
: A buffer in global, fine-grained memory. If a NULL pointer is passed, no operation is performed. If the buffer has been allocated using hsa_memory_allocate, or has already been registered, no operation is performed.[in] size
: Requested registration size in bytes. A size of 0 is only allowed ifptr
is NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:size
is 0 butptr
is not NULL.
-
hsa_status_t HSA_API hsa_region_get_info (hsa_region_t region, hsa_region_info_t attribute, void *value)
Get the current value of an attribute of a region.
- Parameters
[in] region
: A valid region.[in] attribute
: Attribute to query.[out] value
: Pointer to a application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_REGION
: The region is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid region attribute, orvalue
is NULL.
Queue¶
-
enum
hsa_queue_feature_t
¶ Queue features.
Values:
-
enumerator
HSA_QUEUE_FEATURE_KERNEL_DISPATCH
¶ Queue supports kernel dispatch packets.
-
enumerator
HSA_QUEUE_FEATURE_AGENT_DISPATCH
¶ Queue supports agent dispatch packets.
-
enumerator
-
enum
hsa_queue_type_t
¶ Queue type. Intended to be used for dynamic queue protocol determination.
Values:
-
enumerator
HSA_QUEUE_TYPE_MULTI
¶ Queue supports multiple producers.
-
enumerator
HSA_QUEUE_TYPE_SINGLE
¶ Queue only supports a single producer. In some scenarios, the application may want to limit the submission of AQL packets to a single agent. Queues that support a single producer may be more efficient than queues supporting multiple producers.
-
enumerator
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_add_write_index_acq_rel (const hsa_queue_t *queue, uint64_t value)
Atomically increment the write index of a queue by an offset.
- Deprecated:
Renamed as hsa_queue_add_write_index_scacq_screl.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to add to the write index.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_add_write_index_acquire (const hsa_queue_t *queue, uint64_t value)
Atomically increment the write index of a queue by an offset.
- Deprecated:
Renamed as hsa_queue_add_write_index_scacquire.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to add to the write index.
-
uint64_t HSA_API hsa_queue_add_write_index_relaxed (const hsa_queue_t *queue, uint64_t value)
Atomically increment the write index of a queue by an offset.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to add to the write index.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_add_write_index_release (const hsa_queue_t *queue, uint64_t value)
Atomically increment the write index of a queue by an offset.
- Deprecated:
Renamed as hsa_queue_add_write_index_screlease.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to add to the write index.
-
uint64_t HSA_API hsa_queue_add_write_index_scacquire (const hsa_queue_t *queue, uint64_t value)
Atomically increment the write index of a queue by an offset.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to add to the write index.
-
uint64_t HSA_API hsa_queue_add_write_index_screlease (const hsa_queue_t *queue, uint64_t value)
Atomically increment the write index of a queue by an offset.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to add to the write index.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_cas_write_index_acq_rel (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Deprecated:
Renamed as hsa_queue_cas_write_index_scacq_screl.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_cas_write_index_acquire (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Deprecated:
Renamed as hsa_queue_cas_write_index_scacquire.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
uint64_t HSA_API hsa_queue_cas_write_index_relaxed (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_cas_write_index_release (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Deprecated:
Renamed as hsa_queue_cas_write_index_screlease.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
uint64_t HSA_API hsa_queue_cas_write_index_scacq_screl (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
uint64_t HSA_API hsa_queue_cas_write_index_scacquire (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
uint64_t HSA_API hsa_queue_cas_write_index_screlease (const hsa_queue_t *queue, uint64_t expected, uint64_t value)
Atomically set the write index of a queue if the observed value is equal to the expected value. The application can inspect the returned value to determine if the replacement was done.
- Return
Previous value of the write index.
- Parameters
[in] queue
: Pointer to a queue.[in] expected
: Expected value.[in] value
: Value to assign to the write index ifexpected
matches the observed write index. Must be greater thanexpected
.
-
hsa_status_t HSA_API hsa_queue_create (hsa_agent_t agent, uint32_t size, hsa_queue_type32_t type, void(*callback)(hsa_status_t status, hsa_queue_t *source, void *data), void *data, uint32_t private_segment_size, uint32_t group_segment_size, hsa_queue_t **queue)
Create a user mode queue.
The HSA runtime creates the queue structure, the underlying packet buffer, the completion signal, and the write and read indexes. The initial value of the write and read indexes is 0. The type of every packet in the buffer is initialized to HSA_PACKET_TYPE_INVALID.
The application should only rely on the error code returned to determine if the queue is valid.
- Parameters
[in] agent
: Agent where to create the queue.[in] size
: Number of packets the queue is expected to hold. Must be a power of 2 between 1 and the value of HSA_AGENT_INFO_QUEUE_MAX_SIZE inagent
. The size of the newly created queue is the maximum ofsize
and the value of HSA_AGENT_INFO_QUEUE_MIN_SIZE inagent
.[in] type
: Type of the queue. If the value of HSA_AGENT_INFO_QUEUE_TYPE inagent
is HSA_QUEUE_TYPE_SINGLE, thentype
must also be HSA_QUEUE_TYPE_SINGLE.[in] callback
: Callback invoked by the HSA runtime for every asynchronous event related to the newly created queue. May be NULL. The HSA runtime passes three arguments to the callback: a code identifying the event that triggered the invocation, a pointer to the queue where the event originated, and the application data.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.[in] private_segment_size
: Hint indicating the maximum expected private segment usage per work-item, in bytes. There may be performance degradation if the application places a kernel dispatch packet in the queue and the corresponding private segment usage exceedsprivate_segment_size
. If the application does not want to specify any particular value for this argument,private_segment_size
must be UINT32_MAX. If the queue does not support kernel dispatch packets, this argument is ignored.[in] group_segment_size
: Hint indicating the maximum expected group segment usage per work-group, in bytes. There may be performance degradation if the application places a kernel dispatch packet in the queue and the corresponding group segment usage exceedsgroup_segment_size
. If the application does not want to specify any particular value for this argument,group_segment_size
must be UINT32_MAX. If the queue does not support kernel dispatch packets, this argument is ignored.[out] queue
: Memory location where the HSA runtime stores a pointer to the newly created queue.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_QUEUE_CREATION
:agent
does not support queues of the given type.HSA_STATUS_ERROR_INVALID_ARGUMENT
:size
is not a power of two,size
is 0,type
is an invalid queue type, orqueue
is NULL.
-
hsa_status_t HSA_API hsa_queue_destroy (hsa_queue_t *queue)
Destroy a user mode queue.
When a queue is destroyed, the state of the AQL packets that have not been yet fully processed (their completion phase has not finished) becomes undefined. It is the responsibility of the application to ensure that all pending queue operations are finished if their results are required.
The resources allocated by the HSA runtime during queue creation (queue structure, ring buffer, doorbell signal) are released. The queue should not be accessed after being destroyed.
- Parameters
[in] queue
: Pointer to a queue created using hsa_queue_create.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_QUEUE
: The queue is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:queue
is NULL.
-
hsa_status_t HSA_API hsa_queue_inactivate (hsa_queue_t *queue)
Inactivate a queue.
Inactivating the queue aborts any pending executions and prevent any new packets from being processed. Any more packets written to the queue once it is inactivated will be ignored by the packet processor.
- Parameters
[in] queue
: Pointer to a queue.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_QUEUE
: The queue is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:queue
is NULL.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_load_read_index_acquire (const hsa_queue_t *queue)
Atomically load the read index of a queue.
- Deprecated:
Renamed as hsa_queue_load_read_index_scacquire.
- Return
Read index of the queue pointed by
queue
.- Parameters
[in] queue
: Pointer to a queue.
-
uint64_t HSA_API hsa_queue_load_read_index_relaxed (const hsa_queue_t *queue)
Atomically load the read index of a queue.
- Return
Read index of the queue pointed by
queue
.- Parameters
[in] queue
: Pointer to a queue.
-
uint64_t HSA_API hsa_queue_load_read_index_scacquire (const hsa_queue_t *queue)
Atomically load the read index of a queue.
- Return
Read index of the queue pointed by
queue
.- Parameters
[in] queue
: Pointer to a queue.
-
uint64_t HSA_API HSA_DEPRECATED hsa_queue_load_write_index_acquire (const hsa_queue_t *queue)
Atomically load the write index of a queue.
- Deprecated:
Renamed as hsa_queue_load_write_index_scacquire.
- Return
Write index of the queue pointed by
queue
.- Parameters
[in] queue
: Pointer to a queue.
-
uint64_t HSA_API hsa_queue_load_write_index_relaxed (const hsa_queue_t *queue)
Atomically load the write index of a queue.
- Return
Write index of the queue pointed by
queue
.- Parameters
[in] queue
: Pointer to a queue.
-
uint64_t HSA_API hsa_queue_load_write_index_scacquire (const hsa_queue_t *queue)
Atomically load the write index of a queue.
- Return
Write index of the queue pointed by
queue
.- Parameters
[in] queue
: Pointer to a queue.
-
void HSA_API hsa_queue_store_read_index_relaxed (const hsa_queue_t *queue, uint64_t value)
Atomically set the read index of a queue.
Modifications of the read index are not allowed and result in undefined behavior if the queue is associated with an agent for which only the corresponding packet processor is permitted to update the read index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to assign to the read index.
-
void HSA_API HSA_DEPRECATED hsa_queue_store_read_index_release (const hsa_queue_t *queue, uint64_t value)
Atomically set the read index of a queue.
- Deprecated:
Renamed as hsa_queue_store_read_index_screlease.
Modifications of the read index are not allowed and result in undefined behavior if the queue is associated with an agent for which only the corresponding packet processor is permitted to update the read index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to assign to the read index.
-
void HSA_API hsa_queue_store_read_index_screlease (const hsa_queue_t *queue, uint64_t value)
Atomically set the read index of a queue.
Modifications of the read index are not allowed and result in undefined behavior if the queue is associated with an agent for which only the corresponding packet processor is permitted to update the read index.
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to assign to the read index.
-
void HSA_API hsa_queue_store_write_index_relaxed (const hsa_queue_t *queue, uint64_t value)
Atomically set the write index of a queue.
It is recommended that the application uses this function to update the write index when there is a single agent submitting work to the queue (the queue type is HSA_QUEUE_TYPE_SINGLE).
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to assign to the write index.
-
void HSA_API HSA_DEPRECATED hsa_queue_store_write_index_release (const hsa_queue_t *queue, uint64_t value)
Atomically set the write index of a queue.
- Deprecated:
Renamed as hsa_queue_store_write_index_screlease.
It is recommended that the application uses this function to update the write index when there is a single agent submitting work to the queue (the queue type is HSA_QUEUE_TYPE_SINGLE).
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to assign to the write index.
-
void HSA_API hsa_queue_store_write_index_screlease (const hsa_queue_t *queue, uint64_t value)
Atomically set the write index of a queue.
It is recommended that the application uses this function to update the write index when there is a single agent submitting work to the queue (the queue type is HSA_QUEUE_TYPE_SINGLE).
- Parameters
[in] queue
: Pointer to a queue.[in] value
: Value to assign to the write index.
-
hsa_status_t HSA_API hsa_soft_queue_create (hsa_region_t region, uint32_t size, hsa_queue_type32_t type, uint32_t features, hsa_signal_t doorbell_signal, hsa_queue_t **queue)
Create a queue for which the application or a kernel is responsible for processing the AQL packets.
The application can use this function to create queues where AQL packets are not parsed by the packet processor associated with an agent, but rather by a unit of execution running on that agent (for example, a thread in the host application).
The application is responsible for ensuring that all the producers and consumers of the resulting queue can access the provided doorbell signal and memory region. The application is also responsible for ensuring that the unit of execution processing the queue packets supports the indicated features (AQL packet types).
When the queue is created, the HSA runtime allocates the packet buffer using
region
, and the write and read indexes. The initial value of the write and read indexes is 0, and the type of every packet in the buffer is initialized to HSA_PACKET_TYPE_INVALID. The value of the size, type, features, and doorbell_signal fields in the returned queue match the values passed by the application.- Parameters
[in] region
: Memory region that the HSA runtime should use to allocate the AQL packet buffer and any other queue metadata.[in] size
: Number of packets the queue is expected to hold. Must be a power of 2 greater than 0.[in] type
: Queue type.[in] features
: Supported queue features. This is a bit-field of hsa_queue_feature_t values.[in] doorbell_signal
: Doorbell signal that the HSA runtime must associate with the returned queue. The signal handle must not be 0.[out] queue
: Memory location where the HSA runtime stores a pointer to the newly created queue. The application should not rely on the value returned for this argument but only in the status code to determine if the queue is valid. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:size
is not a power of two,size
is 0,type
is an invalid queue type, the doorbell signal handle is 0, orqueue
is NULL.
Architected Queuing Language¶
-
struct
hsa_kernel_dispatch_packet_t
¶ AQL kernel dispatch packet.
-
struct
hsa_agent_dispatch_packet_t
¶ Agent dispatch packet.
-
struct
hsa_barrier_and_packet_t
¶ Barrier-AND packet.
-
struct
hsa_barrier_or_packet_t
¶ Barrier-OR packet.
-
enum
hsa_fence_scope_t
¶ Scope of the memory fence operation associated with a packet.
Values:
-
enumerator
HSA_FENCE_SCOPE_NONE
¶ No scope (no fence is applied). The packet relies on external fences to ensure visibility of memory updates.
-
enumerator
HSA_FENCE_SCOPE_AGENT
¶ The fence is applied with agent scope for the global segment.
-
enumerator
HSA_FENCE_SCOPE_SYSTEM
¶ The fence is applied across both agent and system scope for the global segment.
-
enumerator
-
enum
hsa_kernel_dispatch_packet_setup_t
¶ Sub-fields of the kernel dispatch packet setup field. The offset (with respect to the address of setup) of a sub-field is identical to its enumeration constant. The width of each sub-field is determined by the corresponding value in hsa_kernel_dispatch_packet_setup_width_t. The offset and the width are expressed in bits.
Values:
-
enumerator
HSA_KERNEL_DISPATCH_PACKET_SETUP_DIMENSIONS
¶ Number of dimensions of the grid. Valid values are 1, 2, or 3.
-
enumerator
-
enum
hsa_packet_header_t
¶ Sub-fields of the header field that is present in any AQL packet. The offset (with respect to the address of header) of a sub-field is identical to its enumeration constant. The width of each sub-field is determined by the corresponding value in hsa_packet_header_width_t. The offset and the width are expressed in bits.
Values:
-
enumerator
HSA_PACKET_HEADER_TYPE
¶ Packet type. The value of this sub-field must be one of hsa_packet_type_t. If the type is HSA_PACKET_TYPE_VENDOR_SPECIFIC, the packet layout is vendor-specific.
-
enumerator
HSA_PACKET_HEADER_BARRIER
¶ Barrier bit. If the barrier bit is set, the processing of the current packet only launches when all preceding packets (within the same queue) are complete.
-
enumerator
HSA_PACKET_HEADER_SCACQUIRE_FENCE_SCOPE
¶ Acquire fence scope. The value of this sub-field determines the scope and type of the memory fence operation applied before the packet enters the active phase. An acquire fence ensures that any subsequent global segment or image loads by any unit of execution that belongs to a dispatch that has not yet entered the active phase on any queue of the same kernel agent, sees any data previously released at the scopes specified by the acquire fence. The value of this sub-field must be one of hsa_fence_scope_t.
-
enumerator
HSA_PACKET_HEADER_ACQUIRE_FENCE_SCOPE
¶ - Deprecated:
Renamed as HSA_PACKET_HEADER_SCACQUIRE_FENCE_SCOPE.
-
enumerator
HSA_PACKET_HEADER_SCRELEASE_FENCE_SCOPE
¶ Release fence scope, The value of this sub-field determines the scope and type of the memory fence operation applied after kernel completion but before the packet is completed. A release fence makes any global segment or image data that was stored by any unit of execution that belonged to a dispatch that has completed the active phase on any queue of the same kernel agent visible in all the scopes specified by the release fence. The value of this sub-field must be one of hsa_fence_scope_t.
-
enumerator
HSA_PACKET_HEADER_RELEASE_FENCE_SCOPE
¶ - Deprecated:
Renamed as HSA_PACKET_HEADER_SCRELEASE_FENCE_SCOPE.
-
enumerator
-
enum
hsa_packet_header_width_t
¶ Width (in bits) of the sub-fields in hsa_packet_header_t.
Values:
-
enumerator
HSA_PACKET_HEADER_WIDTH_TYPE
¶
-
enumerator
HSA_PACKET_HEADER_WIDTH_BARRIER
¶
-
enumerator
HSA_PACKET_HEADER_WIDTH_SCACQUIRE_FENCE_SCOPE
¶
-
enumerator
HSA_PACKET_HEADER_WIDTH_ACQUIRE_FENCE_SCOPE
¶ - Deprecated:
Use HSA_PACKET_HEADER_WIDTH_SCACQUIRE_FENCE_SCOPE.
-
enumerator
HSA_PACKET_HEADER_WIDTH_SCRELEASE_FENCE_SCOPE
¶
-
enumerator
HSA_PACKET_HEADER_WIDTH_RELEASE_FENCE_SCOPE
¶ - Deprecated:
Use HSA_PACKET_HEADER_WIDTH_SCRELEASE_FENCE_SCOPE.
-
enumerator
-
enum
hsa_packet_type_t
¶ Packet type.
Values:
-
enumerator
HSA_PACKET_TYPE_VENDOR_SPECIFIC
¶ Vendor-specific packet.
-
enumerator
HSA_PACKET_TYPE_INVALID
¶ The packet has been processed in the past, but has not been reassigned to the packet processor. A packet processor must not process a packet of this type. All queues support this packet type.
-
enumerator
HSA_PACKET_TYPE_KERNEL_DISPATCH
¶ Packet used by agents for dispatching jobs to kernel agents. Not all queues support packets of this type (see hsa_queue_feature_t).
-
enumerator
HSA_PACKET_TYPE_BARRIER_AND
¶ Packet used by agents to delay processing of subsequent packets, and to express complex dependencies between multiple packets. All queues support this packet type.
-
enumerator
HSA_PACKET_TYPE_AGENT_DISPATCH
¶ Packet used by agents for dispatching jobs to agents. Not all queues support packets of this type (see hsa_queue_feature_t).
-
enumerator
HSA_PACKET_TYPE_BARRIER_OR
¶ Packet used by agents to delay processing of subsequent packets, and to express complex dependencies between multiple packets. All queues support this packet type.
-
enumerator
Instruction Set Architecture.¶
-
enum
hsa_flush_mode_t
¶ Flush to zero modes.
Values:
-
enumerator
HSA_FLUSH_MODE_FTZ
¶ Flush to zero.
-
enumerator
HSA_FLUSH_MODE_NON_FTZ
¶ Do not flush to zero.
-
enumerator
-
enum
hsa_fp_type_t
¶ Floating-point types.
Values:
-
enumerator
HSA_FP_TYPE_16
¶ 16-bit floating-point type.
-
enumerator
HSA_FP_TYPE_32
¶ 32-bit floating-point type.
-
enumerator
HSA_FP_TYPE_64
¶ 64-bit floating-point type.
-
enumerator
-
enum
hsa_isa_info_t
¶ Instruction set architecture attributes.
Values:
-
enumerator
HSA_ISA_INFO_NAME_LENGTH
¶ The length of the ISA name in bytes, not including the NUL terminator. The type of this attribute is uint32_t.
-
enumerator
HSA_ISA_INFO_NAME
¶ Human-readable description. The type of this attribute is character array with the length equal to the value of HSA_ISA_INFO_NAME_LENGTH attribute.
-
enumerator
HSA_ISA_INFO_CALL_CONVENTION_COUNT
¶ - Deprecated:
Number of call conventions supported by the instruction set architecture. Must be greater than zero. The type of this attribute is uint32_t.
-
enumerator
HSA_ISA_INFO_CALL_CONVENTION_INFO_WAVEFRONT_SIZE
¶ - Deprecated:
Number of work-items in a wavefront for a given call convention. Must be a power of 2 in the range [1,256]. The type of this attribute is uint32_t.
-
enumerator
HSA_ISA_INFO_CALL_CONVENTION_INFO_WAVEFRONTS_PER_COMPUTE_UNIT
¶ - Deprecated:
Number of wavefronts per compute unit for a given call convention. In practice, other factors (for example, the amount of group memory used by a work-group) may further limit the number of wavefronts per compute unit. The type of this attribute is uint32_t.
-
enumerator
HSA_ISA_INFO_MACHINE_MODELS
¶ Machine models supported by the instruction set architecture. The type of this attribute is a bool[2]. If the ISA supports the small machine model, the element at index HSA_MACHINE_MODEL_SMALL is true. If the ISA supports the large model, the element at index HSA_MACHINE_MODEL_LARGE is true.
-
enumerator
HSA_ISA_INFO_PROFILES
¶ Profiles supported by the instruction set architecture. The type of this attribute is a bool[2]. If the ISA supports the base profile, the element at index HSA_PROFILE_BASE is true. If the ISA supports the full profile, the element at index HSA_PROFILE_FULL is true.
-
enumerator
HSA_ISA_INFO_DEFAULT_FLOAT_ROUNDING_MODES
¶ Default floating-point rounding modes supported by the instruction set architecture. The type of this attribute is a bool[3]. The value at a given index is true if the corresponding rounding mode in hsa_default_float_rounding_mode_t is supported. At least one default mode has to be supported.
If the default mode is supported, then HSA_ISA_INFO_BASE_PROFILE_DEFAULT_FLOAT_ROUNDING_MODES must report that both the zero and the near roundings modes are supported.
-
enumerator
HSA_ISA_INFO_BASE_PROFILE_DEFAULT_FLOAT_ROUNDING_MODES
¶ Default floating-point rounding modes supported by the instruction set architecture in the Base profile. The type of this attribute is a bool[3]. The value at a given index is true if the corresponding rounding mode in hsa_default_float_rounding_mode_t is supported. The value at index HSA_DEFAULT_FLOAT_ROUNDING_MODE_DEFAULT must be false. At least one of the values at indexes HSA_DEFAULT_FLOAT_ROUNDING_MODE_ZERO or HSA_DEFAULT_FLOAT_ROUNDING_MODE_NEAR must be true.
-
enumerator
HSA_ISA_INFO_FAST_F16_OPERATION
¶ Flag indicating that the f16 HSAIL operation is at least as fast as the f32 operation in the instruction set architecture. The type of this attribute is bool.
-
enumerator
HSA_ISA_INFO_WORKGROUP_MAX_DIM
¶ Maximum number of work-items of each dimension of a work-group. Each maximum must be greater than 0. No maximum can exceed the value of HSA_ISA_INFO_WORKGROUP_MAX_SIZE. The type of this attribute is uint16_t[3].
-
enumerator
HSA_ISA_INFO_WORKGROUP_MAX_SIZE
¶ Maximum total number of work-items in a work-group. The type of this attribute is uint32_t.
-
enumerator
HSA_ISA_INFO_GRID_MAX_DIM
¶ Maximum number of work-items of each dimension of a grid. Each maximum must be greater than 0, and must not be smaller than the corresponding value in HSA_ISA_INFO_WORKGROUP_MAX_DIM. No maximum can exceed the value of HSA_ISA_INFO_GRID_MAX_SIZE. The type of this attribute is hsa_dim3_t.
-
enumerator
HSA_ISA_INFO_GRID_MAX_SIZE
¶ Maximum total number of work-items in a grid. The type of this attribute is uint64_t.
-
enumerator
HSA_ISA_INFO_FBARRIER_MAX_SIZE
¶ Maximum number of fbarriers per work-group. Must be at least 32. The type of this attribute is uint32_t.
-
enumerator
-
enum
hsa_round_method_t
¶ Round methods.
Values:
-
enumerator
HSA_ROUND_METHOD_SINGLE
¶ Single round method.
-
enumerator
HSA_ROUND_METHOD_DOUBLE
¶ Double round method.
-
enumerator
-
enum
hsa_wavefront_info_t
¶ Wavefront attributes.
Values:
-
enumerator
HSA_WAVEFRONT_INFO_SIZE
¶ Number of work-items in the wavefront. Must be a power of 2 in the range [1,256]. The type of this attribute is uint32_t.
-
enumerator
-
hsa_status_t HSA_API hsa_agent_iterate_isas (hsa_agent_t agent, hsa_status_t(*callback)(hsa_isa_t isa, void *data), void *data)
Iterate over the instruction sets supported by the given agent, and invoke an application-defined callback on every iteration. The iterator is deterministic: if an agent supports several instruction set architectures, they are traversed in the same order in every invocation of this function.
- Parameters
[in] agent
: A valid agent.[in] callback
: Callback to be invoked once per instruction set architecture. The HSA runtime passes two arguments to the callback: the ISA and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and that status value is returned.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_isa_compatible (hsa_isa_t code_object_isa, hsa_isa_t agent_isa, bool *result)
Check if the instruction set architecture of a code object can be executed on an agent associated with another architecture.
- Deprecated:
Use hsa_agent_iterate_isas to query which instructions set architectures are supported by a given agent.
- Parameters
[in] code_object_isa
: Instruction set architecture associated with a code object.[in] agent_isa
: Instruction set architecture associated with an agent.[out] result
: Pointer to a memory location where the HSA runtime stores the result of the check. If the two architectures are compatible, the result is true; if they are incompatible, the result is false.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA
:code_object_isa
oragent_isa
are invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:result
is NULL.
-
hsa_status_t HSA_API hsa_isa_from_name (const char *name, hsa_isa_t *isa)
Retrieve a reference to an instruction set architecture handle out of a symbolic name.
- Parameters
[in] name
: Vendor-specific name associated with a a particular instruction set architecture.name
must start with the vendor name and a colon (for example, “AMD:”). The rest of the name is vendor-specific. Must be a NUL-terminated string.[out] isa
: Memory location where the HSA runtime stores the ISA handle corresponding to the given name. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA_NAME
: The given name does not correspond to any instruction set architecture.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:name
is NULL, orisa
is NULL.
-
hsa_status_t HSA_API hsa_isa_get_exception_policies (hsa_isa_t isa, hsa_profile_t profile, uint16_t *mask)
Retrieve the exception policy support for a given combination of instruction set architecture and profile.
- Parameters
[in] isa
: A valid instruction set architecture.[in] profile
: Profile.[out] mask
: Pointer to a memory location where the HSA runtime stores a mask of hsa_exception_policy_t values. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA
: The instruction set architecture is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:profile
is not a valid profile, ormask
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_isa_get_info (hsa_isa_t isa, hsa_isa_info_t attribute, uint32_t index, void *value)
Get the current value of an attribute for a given instruction set architecture (ISA).
- Deprecated:
The concept of call convention has been deprecated. If the application wants to query the value of an attribute for a given instruction set architecture, use hsa_isa_get_info_alt instead. If the application wants to query an attribute that is specific to a given combination of ISA and wavefront, use hsa_wavefront_get_info.
- Parameters
[in] isa
: A valid instruction set architecture.[in] attribute
: Attribute to query.[in] index
: Call convention index. Used only for call convention attributes, otherwise ignored. Must have a value between 0 (inclusive) and the value of the attribute HSA_ISA_INFO_CALL_CONVENTION_COUNT (not inclusive) inisa
.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA
: The instruction set architecture is invalid.HSA_STATUS_ERROR_INVALID_INDEX
: The index is out of range.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid instruction set architecture attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_isa_get_info_alt (hsa_isa_t isa, hsa_isa_info_t attribute, void *value)
Get the current value of an attribute for a given instruction set architecture (ISA).
- Parameters
[in] isa
: A valid instruction set architecture.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA
: The instruction set architecture is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid instruction set architecture attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_isa_get_round_method (hsa_isa_t isa, hsa_fp_type_t fp_type, hsa_flush_mode_t flush_mode, hsa_round_method_t *round_method)
Retrieve the round method (single or double) used to implement the floating-point multiply add instruction (mad) for a given combination of instruction set architecture, floating-point type, and flush to zero modifier.
- Parameters
[in] isa
: Instruction set architecture.[in] fp_type
: Floating-point type.[in] flush_mode
: Flush to zero modifier.[out] round_method
: Pointer to a memory location where the HSA runtime stores the round method used by the implementation. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA
: The instruction set architecture is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:fp_type
is not a valid floating-point type, orflush_mode
is not a valid flush to zero modifier, orround_method
is NULL.
-
hsa_status_t HSA_API hsa_isa_iterate_wavefronts (hsa_isa_t isa, hsa_status_t(*callback)(hsa_wavefront_t wavefront, void *data), void *data)
Iterate over the different wavefronts supported by an instruction set architecture, and invoke an application-defined callback on every iteration.
- Parameters
[in] isa
: Instruction set architecture.[in] callback
: Callback to be invoked once per wavefront that is supported by the agent. The HSA runtime passes two arguments to the callback: the wavefront handle and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and that value is returned.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_ISA
: The instruction set architecture is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API hsa_wavefront_get_info (hsa_wavefront_t wavefront, hsa_wavefront_info_t attribute, void *value)
Get the current value of a wavefront attribute.
- Parameters
[in] wavefront
: A wavefront.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_WAVEFRONT
: The wavefront is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid wavefront attribute, orvalue
is NULL.
Executable¶
-
struct
hsa_executable_symbol_t
¶ Executable symbol handle.
The lifetime of an executable object symbol matches that of the executable associated with it. An operation on a symbol whose associated executable has been destroyed results in undefined behavior.
-
enum
hsa_executable_info_t
¶ Executable attributes.
Values:
-
enumerator
HSA_EXECUTABLE_INFO_PROFILE
¶ Profile this executable is created for. The type of this attribute is hsa_profile_t.
-
enumerator
HSA_EXECUTABLE_INFO_STATE
¶ Executable state. The type of this attribute is hsa_executable_state_t.
-
enumerator
HSA_EXECUTABLE_INFO_DEFAULT_FLOAT_ROUNDING_MODE
¶ Default floating-point rounding mode specified when executable was created. The type of this attribute is hsa_default_float_rounding_mode_t.
-
enumerator
-
enum
hsa_executable_state_t
¶ Executable state.
Values:
-
enumerator
HSA_EXECUTABLE_STATE_UNFROZEN
¶ Executable state, which allows the user to load code objects and define external variables. Variable addresses, kernel code handles, and indirect function code handles are not available in query operations until the executable is frozen (zero always returned).
-
enumerator
HSA_EXECUTABLE_STATE_FROZEN
¶ Executable state, which allows the user to query variable addresses, kernel code handles, and indirect function code handles using query operations. Loading new code objects, as well as defining external variables, is not allowed in this state.
-
enumerator
-
enum
hsa_executable_symbol_info_t
¶ Executable symbol attributes.
Values:
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_TYPE
¶ The kind of the symbol. The type of this attribute is hsa_symbol_kind_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_NAME_LENGTH
¶ The length of the symbol name in bytes, not including the NUL terminator. The type of this attribute is uint32_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_NAME
¶ The name of the symbol. The type of this attribute is character array with the length equal to the value of HSA_EXECUTABLE_SYMBOL_INFO_NAME_LENGTH attribute.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_MODULE_NAME_LENGTH
¶ - Deprecated:
The length of the module name in bytes (not including the NUL terminator) to which this symbol belongs if this symbol has module linkage, otherwise 0 is returned. The type of this attribute is uint32_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_MODULE_NAME
¶ - Deprecated:
The module name to which this symbol belongs if this symbol has module linkage, otherwise an empty string is returned. The type of this attribute is character array with the length equal to the value of HSA_EXECUTABLE_SYMBOL_INFO_MODULE_NAME_LENGTH attribute.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_AGENT
¶ - Deprecated:
Agent associated with this symbol. If the symbol is a variable, the value of this attribute is only defined if HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_ALLOCATION is HSA_VARIABLE_ALLOCATION_AGENT. The type of this attribute is hsa_agent_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_ADDRESS
¶ The address of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is uint64_t.
If executable’s state is HSA_EXECUTABLE_STATE_UNFROZEN, then 0 is returned.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_LINKAGE
¶ The linkage kind of the symbol. The type of this attribute is hsa_symbol_linkage_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_IS_DEFINITION
¶ Indicates whether the symbol corresponds to a definition. The type of this attribute is bool.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_ALLOCATION
¶ - Deprecated:
The allocation kind of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is hsa_variable_allocation_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_SEGMENT
¶ - Deprecated:
The segment kind of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is hsa_variable_segment_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_ALIGNMENT
¶ - Deprecated:
Alignment of the symbol in memory. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is uint32_t.
The current alignment of the variable in memory may be greater than the value specified in the source program variable declaration.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_SIZE
¶ - Deprecated:
Size of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is uint32_t.
A value of 0 is returned if the variable is an external variable and has an unknown dimension.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_VARIABLE_IS_CONST
¶ - Deprecated:
Indicates whether the variable is constant. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is bool.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_OBJECT
¶ Kernel object handle, used in the kernel dispatch packet. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint64_t.
If the state of the executable is HSA_EXECUTABLE_STATE_UNFROZEN, then 0 is returned.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_KERNARG_SEGMENT_SIZE
¶ Size of kernarg segment memory that is required to hold the values of the kernel arguments, in bytes. Must be a multiple of 16. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_KERNARG_SEGMENT_ALIGNMENT
¶ Alignment (in bytes) of the buffer used to pass arguments to the kernel, which is the maximum of 16 and the maximum alignment of any of the kernel arguments. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_GROUP_SEGMENT_SIZE
¶ Size of static group segment memory required by the kernel (per work-group), in bytes. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
The reported amount does not include any dynamically allocated group segment memory that may be requested by the application when a kernel is dispatched.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_PRIVATE_SEGMENT_SIZE
¶ Size of static private, spill, and arg segment memory required by this kernel (per work-item), in bytes. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
If the value of HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_DYNAMIC_CALLSTACK is true, the kernel may use more private memory than the reported value, and the application must add the dynamic call stack usage to private_segment_size when populating a kernel dispatch packet.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_DYNAMIC_CALLSTACK
¶ Dynamic callstack flag. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is bool.
If this flag is set (the value is true), the kernel uses a dynamically sized call stack. This can happen if recursive calls, calls to indirect functions, or the HSAIL alloca instruction are present in the kernel.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_KERNEL_CALL_CONVENTION
¶ - Deprecated:
Call convention of the kernel. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_INDIRECT_FUNCTION_OBJECT
¶ Indirect function object handle. The value of this attribute is undefined if the symbol is not an indirect function, or the associated agent does not support the Full Profile. The type of this attribute depends on the machine model: the type is uint32_t for small machine model, and uint64_t for large model.
If the state of the executable is HSA_EXECUTABLE_STATE_UNFROZEN, then 0 is returned.
-
enumerator
HSA_EXECUTABLE_SYMBOL_INFO_INDIRECT_FUNCTION_CALL_CONVENTION
¶ - Deprecated:
Call convention of the indirect function. The value of this attribute is undefined if the symbol is not an indirect function, or the associated agent does not support the Full Profile. The type of this attribute is uint32_t.
-
enumerator
-
enum
hsa_symbol_kind_t
¶ Symbol type.
Values:
-
enumerator
HSA_SYMBOL_KIND_VARIABLE
¶ Variable.
-
enumerator
HSA_SYMBOL_KIND_KERNEL
¶ Kernel.
-
enumerator
HSA_SYMBOL_KIND_INDIRECT_FUNCTION
¶ Indirect function.
-
enumerator
-
enum
hsa_symbol_linkage_t
¶ Linkage type of a symbol.
Values:
-
enumerator
HSA_SYMBOL_LINKAGE_MODULE
¶ Module linkage.
-
enumerator
HSA_SYMBOL_LINKAGE_PROGRAM
¶ Program linkage.
-
enumerator
-
enum
hsa_variable_allocation_t
¶ Allocation type of a variable.
Values:
-
enumerator
HSA_VARIABLE_ALLOCATION_AGENT
¶ Agent allocation.
-
enumerator
HSA_VARIABLE_ALLOCATION_PROGRAM
¶ Program allocation.
-
enumerator
-
enum
hsa_variable_segment_t
¶ Memory segment associated with a variable.
Values:
-
enumerator
HSA_VARIABLE_SEGMENT_GLOBAL
¶ Global memory segment.
-
enumerator
HSA_VARIABLE_SEGMENT_READONLY
¶ Readonly memory segment.
-
enumerator
-
hsa_status_t HSA_API hsa_code_object_reader_create_from_file (hsa_file_t file, hsa_code_object_reader_t *code_object_reader)
Create a code object reader to operate on a file.
The file is owned and managed by the application; the lifetime of the file descriptor must exceed that of any associated code object reader.
- Parameters
[in] file
: File descriptor. The file must have been opened by application with at least read permissions prior calling this function. The file must contain a vendor-specific code object.
- Parameters
[out] code_object_reader
: Memory location to store the newly created code object reader handle. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_FILE
:file
is invalid.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:code_object_reader
is NULL.
-
hsa_status_t HSA_API hsa_code_object_reader_create_from_memory (const void *code_object, size_t size, hsa_code_object_reader_t *code_object_reader)
Create a code object reader to operate on memory.
- Parameters
[in] code_object
: Memory buffer that contains a vendor-specific code object. The buffer is owned and managed by the application; the lifetime of the buffer must exceed that of any associated code object reader.[in] size
: Size of the buffer pointed to bycode_object
. Must not be 0.[out] code_object_reader
: Memory location to store newly created code object reader handle. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:code_object
is NULL,size
is zero, orcode_object_reader
is NULL.
-
hsa_status_t HSA_API hsa_code_object_reader_destroy (hsa_code_object_reader_t code_object_reader)
Destroy a code object reader.
The code object reader handle becomes invalid after completion of this function. Any file or memory used to create the code object read is not closed, removed, or deallocated by this function.
- Parameters
[in] code_object_reader
: Code object reader to destroy.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_OBJECT_READER
:code_object_reader
is invalid.
-
hsa_status_t HSA_API hsa_executable_agent_global_variable_define (hsa_executable_t executable, hsa_agent_t agent, const char *variable_name, void *address)
Define an external global variable with agent allocation.
This function allows the application to provide the definition of a variable in the global segment memory with agent allocation. The variable must be defined before loading a code object into an executable. In addition, code objects loaded must not define the variable.
- Parameters
[in] executable
: Executable. Must not be in frozen state.[in] agent
: Agent for which the variable is being defined.[in] variable_name
: Name of the variable. The Programmer’s Reference Manual describes the standard name mangling scheme.[in] address
: Address where the variable is defined. This address must have been previously allocated using hsa_memory_allocate in a global region that is only visible toagent
. The application cannot deallocate the buffer pointed byaddress
beforeexecutable
is destroyed.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_AGENT
:agent
is invalid.HSA_STATUS_ERROR_VARIABLE_ALREADY_DEFINED
: The variable is already defined.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no variable with thevariable_name
.HSA_STATUS_ERROR_FROZEN_EXECUTABLE
:executable
is frozen.HSA_STATUS_ERROR_INVALID_ARGUMENT
:variable_name
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_executable_create (hsa_profile_t profile, hsa_executable_state_t executable_state, const char *options, hsa_executable_t *executable)
Create an empty executable.
- Deprecated:
Use hsa_executable_create_alt instead, which allows the application to specify the default floating-point rounding mode of the executable and assumes an unfrozen initial state.
- Parameters
[in] profile
: Profile used in the executable.[in] executable_state
: Executable state. If the state is HSA_EXECUTABLE_STATE_FROZEN, the resulting executable is useless because no code objects can be loaded, and no variables can be defined.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] executable
: Memory location where the HSA runtime stores the newly created executable handle.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:profile
is invalid, orexecutable
is NULL.
-
hsa_status_t HSA_API hsa_executable_create_alt (hsa_profile_t profile, hsa_default_float_rounding_mode_t default_float_rounding_mode, const char *options, hsa_executable_t *executable)
Create an empty executable.
- Parameters
[in] profile
: Profile used in the executable.[in] default_float_rounding_mode
: Default floating-point rounding mode used in the executable. Allowed rounding modes are near and zero (default is not allowed).[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] executable
: Memory location where the HSA runtime stores newly created executable handle. The initial state of the executable is HSA_EXECUTABLE_STATE_UNFROZEN.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:profile
is invalid, orexecutable
is NULL.
-
hsa_status_t HSA_API hsa_executable_destroy (hsa_executable_t executable)
Destroy an executable.
An executable handle becomes invalid after the executable has been destroyed. Code object handles that were loaded into this executable are still valid after the executable has been destroyed, and can be used as intended. Resources allocated outside and associated with this executable (such as external global or readonly variables) can be released after the executable has been destroyed.
Executable should not be destroyed while kernels are in flight.
- Parameters
[in] executable
: Executable.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.
-
hsa_status_t HSA_API hsa_executable_freeze (hsa_executable_t executable, const char *options)
Freeze the executable.
No modifications to executable can be made after freezing: no code objects can be loaded to the executable, and no external variables can be defined. Freezing the executable does not prevent querying the executable’s attributes. The application must define all the external variables in an executable before freezing it.
- Parameters
[in] executable
: Executable.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_VARIABLE_UNDEFINED
: One or more variables are undefined in the executable.HSA_STATUS_ERROR_FROZEN_EXECUTABLE
:executable
is already frozen.
-
hsa_status_t HSA_API hsa_executable_get_info (hsa_executable_t executable, hsa_executable_info_t attribute, void *value)
Get the current value of an attribute for a given executable.
- Parameters
[in] executable
: Executable.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid executable attribute, orvalue
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_executable_get_symbol (hsa_executable_t executable, const char *module_name, const char *symbol_name, hsa_agent_t agent, int32_t call_convention, hsa_executable_symbol_t *symbol)
Get the symbol handle for a given a symbol name.
- Deprecated:
Use hsa_executable_get_symbol_by_name instead.
- Parameters
[in] executable
: Executable.[in] module_name
: Module name. Must be NULL if the symbol has program linkage.[in] symbol_name
: Symbol name.[in] agent
: Agent associated with the symbol. If the symbol is independent of any agent (for example, a variable with program allocation), this argument is ignored.[in] call_convention
: Call convention associated with the symbol. If the symbol does not correspond to an indirect function, this argument is ignored.[out] symbol
: Memory location where the HSA runtime stores the symbol handle.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no symbol with a name that matchessymbol_name
.HSA_STATUS_ERROR_INVALID_ARGUMENT
:symbol_name
is NULL, orsymbol
is NULL.
-
hsa_status_t HSA_API hsa_executable_get_symbol_by_name (hsa_executable_t executable, const char *symbol_name, const hsa_agent_t *agent, hsa_executable_symbol_t *symbol)
Retrieve the symbol handle corresponding to a given a symbol name.
- Parameters
[in] executable
: Executable.[in] symbol_name
: Symbol name. Must be a NUL-terminated character array. The Programmer’s Reference Manual describes the standard name mangling scheme.[in] agent
: Pointer to the agent for which the symbol with the given name is defined. If the symbol corresponding to the given name has program allocation,agent
must be NULL.[out] symbol
: Memory location where the HSA runtime stores the symbol handle. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no symbol with a name that matchessymbol_name
.HSA_STATUS_ERROR_INVALID_ARGUMENT
:symbol_name
is NULL, orsymbol
is NULL.
-
hsa_status_t HSA_API hsa_executable_global_variable_define (hsa_executable_t executable, const char *variable_name, void *address)
Define an external global variable with program allocation.
This function allows the application to provide the definition of a variable in the global segment memory with program allocation. The variable must be defined before loading a code object into an executable. In addition, code objects loaded must not define the variable.
- Parameters
[in] executable
: Executable. Must not be in frozen state.[in] variable_name
: Name of the variable. The Programmer’s Reference Manual describes the standard name mangling scheme.[in] address
: Address where the variable is defined. This address must be in global memory and can be read and written by any agent in the system. The application cannot deallocate the buffer pointed byaddress
beforeexecutable
is destroyed.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_VARIABLE_ALREADY_DEFINED
: The variable is already defined.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no variable with thevariable_name
.HSA_STATUS_ERROR_FROZEN_EXECUTABLE
:executable
is frozen.HSA_STATUS_ERROR_INVALID_ARGUMENT
:variable_name
is NULL.
-
hsa_status_t HSA_API hsa_executable_iterate_agent_symbols (hsa_executable_t executable, hsa_agent_t agent, hsa_status_t(*callback)(hsa_executable_t exec, hsa_agent_t agent, hsa_executable_symbol_t symbol, void *data), void *data)
Iterate over the kernels, indirect functions, and agent allocation variables in an executable for a given agent, and invoke an application- defined callback on every iteration.
- Parameters
[in] executable
: Executable.[in] agent
: Agent.[in] callback
: Callback to be invoked once per executable symbol. The HSA runtime passes three arguments to the callback: the executable, a symbol, and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_executable_iterate_symbols returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API hsa_executable_iterate_program_symbols (hsa_executable_t executable, hsa_status_t(*callback)(hsa_executable_t exec, hsa_executable_symbol_t symbol, void *data), void *data)
Iterate over the program allocation variables in an executable, and invoke an application-defined callback on every iteration.
- Parameters
[in] executable
: Executable.[in] callback
: Callback to be invoked once per executable symbol. The HSA runtime passes three arguments to the callback: the executable, a symbol, and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_executable_iterate_symbols returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_executable_iterate_symbols (hsa_executable_t executable, hsa_status_t(*callback)(hsa_executable_t exec, hsa_executable_symbol_t symbol, void *data), void *data)
Iterate over the symbols in a executable, and invoke an application-defined callback on every iteration.
- Deprecated:
- Parameters
[in] executable
: Executable.[in] callback
: Callback to be invoked once per executable symbol. The HSA runtime passes three arguments to the callback: the executable, a symbol, and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_executable_iterate_symbols returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API hsa_executable_load_agent_code_object (hsa_executable_t executable, hsa_agent_t agent, hsa_code_object_reader_t code_object_reader, const char *options, hsa_loaded_code_object_t *loaded_code_object)
Load an agent code object into an executable.
The agent code object contains all defined agent allocation variables, functions, indirect functions, and kernels in a given program for a given instruction set architecture.
Any module linkage declaration must have been defined either by a define variable or by loading a code object that has a symbol with module linkage definition.
The default floating-point rounding mode of the code object associated with
code_object_reader
must match that of the executable (HSA_EXECUTABLE_INFO_DEFAULT_FLOAT_ROUNDING_MODE), or be default (in which case the value of HSA_EXECUTABLE_INFO_DEFAULT_FLOAT_ROUNDING_MODE is used). If the agent code object uses extensions, the implementation and the agent must support them for this operation to return successfully.- Parameters
[in] executable
: Executable.[in] agent
: Agent to load code object for. A code object can be loaded into an executable at most once for a given agent. The instruction set architecture of the code object must be supported by the agent.[in] code_object_reader
: A code object reader that holds the code object to load. If a code object reader is destroyed before all the associated executables are destroyed, the behavior is undefined.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] loaded_code_object
: Pointer to a memory location where the HSA runtime stores the loaded code object handle. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_FROZEN_EXECUTABLE
: The executable is frozen.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_CODE_OBJECT_READER
:code_object_reader
is invalid.HSA_STATUS_ERROR_INCOMPATIBLE_ARGUMENTS
: The code object read bycode_object_reader
is not compatible with the agent (for example, the agent does not support the instruction set architecture of the code object), the executable (for example, there is a default floating-point mode mismatch between the two), or the implementation.
-
hsa_status_t HSA_API hsa_executable_load_program_code_object (hsa_executable_t executable, hsa_code_object_reader_t code_object_reader, const char *options, hsa_loaded_code_object_t *loaded_code_object)
Load a program code object into an executable.
A program code object contains information about resources that are accessible by all kernel agents that run the executable, and can be loaded at most once into an executable.
If the program code object uses extensions, the implementation must support them for this operation to return successfully.
- Parameters
[in] executable
: Executable.[in] code_object_reader
: A code object reader that holds the program code object to load. If a code object reader is destroyed before all the associated executables are destroyed, the behavior is undefined.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] loaded_code_object
: Pointer to a memory location where the HSA runtime stores the loaded code object handle. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_FROZEN_EXECUTABLE
: The executable is frozen.HSA_STATUS_ERROR_INVALID_CODE_OBJECT_READER
:code_object_reader
is invalid.HSA_STATUS_ERROR_INCOMPATIBLE_ARGUMENTS
: The program code object is not compatible with the executable or the implementation (for example, the code object uses an extension that is not supported by the implementation).
-
hsa_status_t HSA_API hsa_executable_readonly_variable_define (hsa_executable_t executable, hsa_agent_t agent, const char *variable_name, void *address)
Define an external readonly variable.
This function allows the application to provide the definition of a variable in the readonly segment memory. The variable must be defined before loading a code object into an executable. In addition, code objects loaded must not define the variable.
- Parameters
[in] executable
: Executable. Must not be in frozen state.[in] agent
: Agent for which the variable is being defined.[in] variable_name
: Name of the variable. The Programmer’s Reference Manual describes the standard name mangling scheme.[in] address
: Address where the variable is defined. This address must have been previously allocated using hsa_memory_allocate in a readonly region associated withagent
. The application cannot deallocate the buffer pointed byaddress
beforeexecutable
is destroyed.[in] address
: Address where the variable is defined. The buffer pointed byaddress
is owned by the application, and cannot be deallocated beforeexecutable
is destroyed.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: Executable is invalid.HSA_STATUS_ERROR_INVALID_AGENT
:agent
is invalid.HSA_STATUS_ERROR_VARIABLE_ALREADY_DEFINED
: The variable is already defined.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no variable with thevariable_name
.HSA_STATUS_ERROR_FROZEN_EXECUTABLE
:executable
is frozen.HSA_STATUS_ERROR_INVALID_ARGUMENT
:variable_name
is NULL.
-
hsa_status_t HSA_API hsa_executable_symbol_get_info (hsa_executable_symbol_t executable_symbol, hsa_executable_symbol_info_t attribute, void *value)
Get the current value of an attribute for a given executable symbol.
- Parameters
[in] executable_symbol
: Executable symbol.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE_SYMBOL
: The executable symbol is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid executable symbol attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_executable_validate (hsa_executable_t executable, uint32_t *result)
Validate an executable. Checks that all code objects have matching machine model, profile, and default floating-point rounding mode. Checks that all declarations have definitions. Checks declaration-definition compatibility (see the HSA Programming Reference Manual for compatibility rules). Invoking this function is equivalent to invoking hsa_executable_validate_alt with no options.
- Parameters
[in] executable
: Executable. Must be in frozen state.[out] result
: Memory location where the HSA runtime stores the validation result. If the executable passes validation, the result is 0.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
:executable
is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:result
is NULL.
-
hsa_status_t HSA_API hsa_executable_validate_alt (hsa_executable_t executable, const char *options, uint32_t *result)
Validate an executable. Checks that all code objects have matching machine model, profile, and default floating-point rounding mode. Checks that all declarations have definitions. Checks declaration-definition compatibility (see the HSA Programming Reference Manual for compatibility rules).
- Parameters
[in] executable
: Executable. Must be in frozen state.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] result
: Memory location where the HSA runtime stores the validation result. If the executable passes validation, the result is 0.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_EXECUTABLE
:executable
is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:result
is NULL.
Code Objects (deprecated).¶
-
enum
hsa_code_object_type_t
¶ Code object type.
- Deprecated:
Values:
-
enumerator
HSA_CODE_OBJECT_TYPE_PROGRAM
¶ Produces code object that contains ISA for all kernels and indirect functions in HSA source.
-
enum
hsa_code_symbol_info_t
¶ Code object symbol attributes.
- Deprecated:
Values:
-
enumerator
HSA_CODE_SYMBOL_INFO_TYPE
¶ The type of the symbol. The type of this attribute is hsa_symbol_kind_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_NAME_LENGTH
¶ The length of the symbol name in bytes, not including the NUL terminator. The type of this attribute is uint32_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_NAME
¶ The name of the symbol. The type of this attribute is character array with the length equal to the value of HSA_CODE_SYMBOL_INFO_NAME_LENGTH attribute.
-
enumerator
HSA_CODE_SYMBOL_INFO_MODULE_NAME_LENGTH
¶ The length of the module name in bytes (not including the NUL terminator) to which this symbol belongs if this symbol has module linkage, otherwise 0 is returned. The type of this attribute is uint32_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_MODULE_NAME
¶ The module name to which this symbol belongs if this symbol has module linkage, otherwise an empty string is returned. The type of this attribute is character array with the length equal to the value of HSA_CODE_SYMBOL_INFO_MODULE_NAME_LENGTH attribute.
-
enumerator
HSA_CODE_SYMBOL_INFO_LINKAGE
¶ The linkage kind of the symbol. The type of this attribute is hsa_symbol_linkage_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_IS_DEFINITION
¶ Indicates whether the symbol corresponds to a definition. The type of this attribute is bool.
-
enumerator
HSA_CODE_SYMBOL_INFO_VARIABLE_ALLOCATION
¶ The allocation kind of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is hsa_variable_allocation_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_VARIABLE_SEGMENT
¶ The segment kind of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is hsa_variable_segment_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_VARIABLE_ALIGNMENT
¶ Alignment of the symbol in memory. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is uint32_t.
The current alignment of the variable in memory may be greater than the value specified in the source program variable declaration.
-
enumerator
HSA_CODE_SYMBOL_INFO_VARIABLE_SIZE
¶ Size of the variable. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is uint32_t.
A size of 0 is returned if the variable is an external variable and has an unknown dimension.
-
enumerator
HSA_CODE_SYMBOL_INFO_VARIABLE_IS_CONST
¶ Indicates whether the variable is constant. The value of this attribute is undefined if the symbol is not a variable. The type of this attribute is bool.
-
enumerator
HSA_CODE_SYMBOL_INFO_KERNEL_KERNARG_SEGMENT_SIZE
¶ Size of kernarg segment memory that is required to hold the values of the kernel arguments, in bytes. Must be a multiple of 16. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_KERNEL_KERNARG_SEGMENT_ALIGNMENT
¶ Alignment (in bytes) of the buffer used to pass arguments to the kernel, which is the maximum of 16 and the maximum alignment of any of the kernel arguments. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_KERNEL_GROUP_SEGMENT_SIZE
¶ Size of static group segment memory required by the kernel (per work-group), in bytes. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
The reported amount does not include any dynamically allocated group segment memory that may be requested by the application when a kernel is dispatched.
-
enumerator
HSA_CODE_SYMBOL_INFO_KERNEL_PRIVATE_SEGMENT_SIZE
¶ Size of static private, spill, and arg segment memory required by this kernel (per work-item), in bytes. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
If the value of HSA_CODE_SYMBOL_INFO_KERNEL_DYNAMIC_CALLSTACK is true, the kernel may use more private memory than the reported value, and the application must add the dynamic call stack usage to private_segment_size when populating a kernel dispatch packet.
-
enumerator
HSA_CODE_SYMBOL_INFO_KERNEL_DYNAMIC_CALLSTACK
¶ Dynamic callstack flag. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is bool.
If this flag is set (the value is true), the kernel uses a dynamically sized call stack. This can happen if recursive calls, calls to indirect functions, or the HSAIL alloca instruction are present in the kernel.
-
enumerator
HSA_CODE_SYMBOL_INFO_KERNEL_CALL_CONVENTION
¶ Call convention of the kernel. The value of this attribute is undefined if the symbol is not a kernel. The type of this attribute is uint32_t.
-
enumerator
HSA_CODE_SYMBOL_INFO_INDIRECT_FUNCTION_CALL_CONVENTION
¶ Call convention of the indirect function. The value of this attribute is undefined if the symbol is not an indirect function. The type of this attribute is uint32_t.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_deserialize (void *serialized_code_object, size_t serialized_code_object_size, const char *options, hsa_code_object_t *code_object)
Deserialize a code object.
- Deprecated:
- Parameters
[in] serialized_code_object
: A serialized code object. Must not be NULL.[in] serialized_code_object_size
: The size (in bytes) ofserialized_code_object
. Must not be 0.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] code_object
: Memory location where the HSA runtime stores the deserialized code object.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_ARGUMENT
:serialized_code_object
, orcode_object
are NULL, orserialized_code_object_size
is 0.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_destroy (hsa_code_object_t code_object)
Destroy a code object.
- Deprecated:
The lifetime of a code object must exceed that of any executable where it has been loaded. If an executable that loaded
code_object
has not been destroyed, the behavior is undefined.- Parameters
[in] code_object
: Code object. The handle becomes invalid after it has been destroyed.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_get_info (hsa_code_object_t code_object, hsa_code_object_info_t attribute, void *value)
Get the current value of an attribute for a given code object.
- Deprecated:
- Parameters
[in] code_object
: Code object.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid code object attribute, orvalue
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_get_symbol (hsa_code_object_t code_object, const char *symbol_name, hsa_code_symbol_t *symbol)
Get the symbol handle within a code object for a given a symbol name.
- Deprecated:
- Parameters
[in] code_object
: Code object.[in] symbol_name
: Symbol name.[out] symbol
: Memory location where the HSA runtime stores the symbol handle.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no symbol with a name that matchessymbol_name
.HSA_STATUS_ERROR_INVALID_ARGUMENT
:symbol_name
is NULL, orsymbol
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_get_symbol_from_name (hsa_code_object_t code_object, const char *module_name, const char *symbol_name, hsa_code_symbol_t *symbol)
Get the symbol handle within a code object for a given a symbol name.
- Deprecated:
- Parameters
[in] code_object
: Code object.[in] module_name
: Module name. Must be NULL if the symbol has program linkage.[in] symbol_name
: Symbol name.[out] symbol
: Memory location where the HSA runtime stores the symbol handle.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.HSA_STATUS_ERROR_INVALID_SYMBOL_NAME
: There is no symbol with a name that matchessymbol_name
.HSA_STATUS_ERROR_INVALID_ARGUMENT
:symbol_name
is NULL, orsymbol
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_iterate_symbols (hsa_code_object_t code_object, hsa_status_t(*callback)(hsa_code_object_t code_object, hsa_code_symbol_t symbol, void *data), void *data)
Iterate over the symbols in a code object, and invoke an application-defined callback on every iteration.
- Deprecated:
- Parameters
[in] code_object
: Code object.[in] callback
: Callback to be invoked once per code object symbol. The HSA runtime passes three arguments to the callback: the code object, a symbol, and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_code_object_iterate_symbols returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_object_serialize (hsa_code_object_t code_object, hsa_status_t(*alloc_callback)(size_t size, hsa_callback_data_t data, void **address), hsa_callback_data_t callback_data, const char *options, void **serialized_code_object, size_t *serialized_code_object_size)
Serialize a code object. Can be used for offline finalization, install-time finalization, disk code caching, etc.
- Deprecated:
- Parameters
[in] code_object
: Code object.[in] alloc_callback
: Callback function for memory allocation. Must not be NULL. The HSA runtime passes three arguments to the callback: the allocation size, the application data, and a pointer to a memory location where the application stores the allocation result. The HSA runtime invokesalloc_callback
once to allocate a buffer that contains the serialized version ofcode_object
. If the callback returns a status code other than HSA_STATUS_SUCCESS, this function returns the same code.[in] callback_data
: Application data that is passed toalloc_callback
. May be NULL.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.[out] serialized_code_object
: Memory location where the HSA runtime stores a pointer to the serialized code object. Must not be NULL.[out] serialized_code_object_size
: Memory location where the HSA runtime stores the size (in bytes) ofserialized_code_object
. The returned value matches the allocation size passed by the HSA runtime toalloc_callback
. Must not be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:alloc_callback
,serialized_code_object
, orserialized_code_object_size
are NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_code_symbol_get_info (hsa_code_symbol_t code_symbol, hsa_code_symbol_info_t attribute, void *value)
Get the current value of an attribute for a given code symbol.
- Deprecated:
- Parameters
[in] code_symbol
: Code symbol.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behavior is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_INVALID_CODE_SYMBOL
: The code symbol is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid code symbol attribute, orvalue
is NULL.
-
hsa_status_t HSA_API HSA_DEPRECATED hsa_executable_load_code_object (hsa_executable_t executable, hsa_agent_t agent, hsa_code_object_t code_object, const char *options)
Load code object into the executable.
- Deprecated:
Every global or readonly variable that is external must be defined before loading the code object. An internal global or readonly variable is allocated once the code object, that is being loaded, references this variable and this variable is not allocated.
Any module linkage declaration must have been defined either by a define variable or by loading a code object that has a symbol with module linkage definition.
- Parameters
[in] executable
: Executable.[in] agent
: Agent to load code object for. The agent must support the default floating-point rounding mode used bycode_object
.[in] code_object
: Code object to load. The lifetime of the code object must exceed that of the executable: ifcode_object
is destroyed beforeexecutable
, the behavior is undefined.[in] options
: Standard and vendor-specific options. Unknown options are ignored. A standard option begins with the “-hsa_” prefix. Options beginning with the “-hsa_ext_<extension_name>_” prefix are reserved for extensions. A vendor-specific option begins with the “-<vendor_name>_” prefix. Must be a NUL-terminated string. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: The HSA runtime failed to allocate the required resources.HSA_STATUS_ERROR_INVALID_EXECUTABLE
: The executable is invalid.HSA_STATUS_ERROR_INVALID_AGENT
: The agent is invalid.HSA_STATUS_ERROR_INVALID_CODE_OBJECT
:code_object
is invalid.HSA_STATUS_ERROR_INCOMPATIBLE_ARGUMENTS
:agent
is not compatible withcode_object
(for example,agent
does not support the default floating-point rounding mode specified bycode_object
), orcode_object
is not compatible withexecutable
(for example,code_object
andexecutable
have different machine models or profiles).HSA_STATUS_ERROR_FROZEN_EXECUTABLE
:executable
is frozen.
Finalization Program¶
-
enum
hsa_ext_finalizer_call_convention_t
¶ Finalizer-determined call convention.
Values:
-
enumerator
HSA_EXT_FINALIZER_CALL_CONVENTION_AUTO
¶ Finalizer-determined call convention.
-
enumerator
-
enum
hsa_ext_program_info_t
¶ HSAIL program attributes.
Values:
-
enumerator
HSA_EXT_PROGRAM_INFO_MACHINE_MODEL
¶ Machine model specified when the HSAIL program was created. The type of this attribute is hsa_machine_model_t.
-
enumerator
HSA_EXT_PROGRAM_INFO_PROFILE
¶ Profile specified when the HSAIL program was created. The type of this attribute is hsa_profile_t.
-
enumerator
HSA_EXT_PROGRAM_INFO_DEFAULT_FLOAT_ROUNDING_MODE
¶ Default float rounding mode specified when the HSAIL program was created. The type of this attribute is hsa_default_float_rounding_mode_t.
-
enumerator
-
hsa_status_t HSA_API hsa_ext_program_add_module (hsa_ext_program_t program, hsa_ext_module_t module)
Add a HSAIL module to an existing HSAIL program.
The HSA runtime does not perform a deep copy of the HSAIL module upon addition. Instead, it stores a pointer to the HSAIL module. The ownership of the HSAIL module belongs to the application, which must ensure that
module
is not released before destroying the HSAIL program.The HSAIL module is successfully added to the HSAIL program if
module
is valid, if all the declarations and definitions for the same symbol are compatible, and ifmodule
specify machine model and profile that matches the HSAIL program.- Parameters
[in] program
: HSAIL program.[in] module
: HSAIL module. The application can add the same HSAIL module toprogram
at most once. The HSAIL module must specify the same machine model and profile asprogram
. If the floating-mode rounding mode ofmodule
is not default, then it should match that ofprogram
.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: There is a failure to allocate resources required for the operation.HSA_EXT_STATUS_ERROR_INVALID_PROGRAM
: The HSAIL program is invalid.HSA_EXT_STATUS_ERROR_INVALID_MODULE
: The HSAIL module is invalid.HSA_EXT_STATUS_ERROR_INCOMPATIBLE_MODULE
: The machine model ofmodule
does not match machine model ofprogram
, or the profile ofmodule
does not match profile ofprogram
.HSA_EXT_STATUS_ERROR_MODULE_ALREADY_INCLUDED
: The HSAIL module is already a part of the HSAIL program.HSA_EXT_STATUS_ERROR_SYMBOL_MISMATCH
: Symbol declaration and symbol definition compatibility mismatch. See the symbol compatibility rules in the HSA Programming Reference Manual.
-
hsa_status_t HSA_API hsa_ext_program_create (hsa_machine_model_t machine_model, hsa_profile_t profile, hsa_default_float_rounding_mode_t default_float_rounding_mode, const char *options, hsa_ext_program_t *program)
Create an empty HSAIL program.
- Parameters
[in] machine_model
: Machine model used in the HSAIL program.[in] profile
: Profile used in the HSAIL program.[in] default_float_rounding_mode
: Default float rounding mode used in the HSAIL program.[in] options
: Vendor-specific options. May be NULL.[out] program
: Memory location where the HSA runtime stores the newly created HSAIL program handle.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: There is a failure to allocate resources required for the operation.HSA_STATUS_ERROR_INVALID_ARGUMENT
:machine_model
is invalid,profile
is invalid,default_float_rounding_mode
is invalid, orprogram
is NULL.
-
hsa_status_t HSA_API hsa_ext_program_destroy (hsa_ext_program_t program)
Destroy a HSAIL program.
The HSAIL program handle becomes invalid after it has been destroyed. Code object handles produced by hsa_ext_program_finalize are still valid after the HSAIL program has been destroyed, and can be used as intended. Resources allocated outside and associated with the HSAIL program (such as HSAIL modules that are added to the HSAIL program) can be released after the finalization program has been destroyed.
- Parameters
[in] program
: HSAIL program.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_EXT_STATUS_ERROR_INVALID_PROGRAM
: The HSAIL program is invalid.
-
hsa_status_t HSA_API hsa_ext_program_finalize (hsa_ext_program_t program, hsa_isa_t isa, int32_t call_convention, hsa_ext_control_directives_t control_directives, const char *options, hsa_code_object_type_t code_object_type, hsa_code_object_t *code_object)
Finalize an HSAIL program for a given instruction set architecture.
Finalize all of the kernels and indirect functions that belong to the same HSAIL program for a specific instruction set architecture (ISA). The transitive closure of all functions specified by call or scall must be defined. Kernels and indirect functions that are being finalized must be defined. Kernels and indirect functions that are referenced in kernels and indirect functions being finalized may or may not be defined, but must be declared. All the global/readonly segment variables that are referenced in kernels and indirect functions being finalized may or may not be defined, but must be declared.
- Parameters
[in] program
: HSAIL program.[in] isa
: Instruction set architecture to finalize for.[in] call_convention
: A call convention used in a finalization. Must have a value between HSA_EXT_FINALIZER_CALL_CONVENTION_AUTO (inclusive) and the value of the attribute HSA_ISA_INFO_CALL_CONVENTION_COUNT inisa
(not inclusive).[in] control_directives
: Low-level control directives that influence the finalization process.[in] options
: Vendor-specific options. May be NULL.[in] code_object_type
: Type of code object to produce.[out] code_object
: Code object generated by the Finalizer, which contains the machine code for the kernels and indirect functions in the HSAIL program. The code object is independent of the HSAIL module that was used to generate it.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_STATUS_ERROR_OUT_OF_RESOURCES
: There is a failure to allocate resources required for the operation.HSA_EXT_STATUS_ERROR_INVALID_PROGRAM
: The HSAIL program is invalid.HSA_STATUS_ERROR_INVALID_ISA
:isa
is invalid.HSA_EXT_STATUS_ERROR_DIRECTIVE_MISMATCH
: The directive in the control directive structure and in the HSAIL kernel mismatch, or if the same directive is used with a different value in one of the functions used by this kernel.HSA_EXT_STATUS_ERROR_FINALIZATION_FAILED
: The Finalizer encountered an error while compiling a kernel or an indirect function.
-
hsa_status_t HSA_API hsa_ext_program_get_info (hsa_ext_program_t program, hsa_ext_program_info_t attribute, void *value)
Get the current value of an attribute for a given HSAIL program.
- Parameters
[in] program
: HSAIL program.[in] attribute
: Attribute to query.[out] value
: Pointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value ofattribute
, the behaviour is undefined.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_EXT_STATUS_ERROR_INVALID_PROGRAM
: The HSAIL program is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:attribute
is an invalid HSAIL program attribute, orvalue
is NULL.
-
hsa_status_t HSA_API hsa_ext_program_iterate_modules (hsa_ext_program_t program, hsa_status_t(*callback)(hsa_ext_program_t program, hsa_ext_module_t module, void *data), void *data)
Iterate over the HSAIL modules in a program, and invoke an application-defined callback on every iteration.
- Parameters
[in] program
: HSAIL program.[in] callback
: Callback to be invoked once per HSAIL module in the program. The HSA runtime passes three arguments to the callback: the program, a HSAIL module, and the application data. Ifcallback
returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_ext_program_iterate_modules returns that status value.[in] data
: Application data that is passed tocallback
on every iteration. May be NULL.
- Return Value
HSA_STATUS_SUCCESS
: The function has been executed successfully.HSA_STATUS_ERROR_NOT_INITIALIZED
: The HSA runtime has not been initialized.HSA_EXT_STATUS_ERROR_INVALID_PROGRAM
: The program is invalid.HSA_STATUS_ERROR_INVALID_ARGUMENT
:callback
is NULL.