Instruction Set Architecture.

Classes
struct	hsa_isa_s
	Instruction set architecture. More...
struct	hsa_wavefront_s
	Wavefront handle. More...

Typedefs
typedef struct hsa_isa_s	hsa_isa_t
	Instruction set architecture.
typedef struct hsa_wavefront_s	hsa_wavefront_t
	Wavefront handle.

Enumerations
enum	hsa_isa_info_t {   HSA_ISA_INFO_NAME_LENGTH = 0 , HSA_ISA_INFO_NAME = 1 , HSA_ISA_INFO_CALL_CONVENTION_COUNT = 2 , HSA_ISA_INFO_CALL_CONVENTION_INFO_WAVEFRONT_SIZE = 3 ,   HSA_ISA_INFO_CALL_CONVENTION_INFO_WAVEFRONTS_PER_COMPUTE_UNIT = 4 , HSA_ISA_INFO_MACHINE_MODELS = 5 , HSA_ISA_INFO_PROFILES = 6 , HSA_ISA_INFO_DEFAULT_FLOAT_ROUNDING_MODES = 7 ,   HSA_ISA_INFO_BASE_PROFILE_DEFAULT_FLOAT_ROUNDING_MODES = 8 , HSA_ISA_INFO_FAST_F16_OPERATION = 9 , HSA_ISA_INFO_WORKGROUP_MAX_DIM = 12 , HSA_ISA_INFO_WORKGROUP_MAX_SIZE = 13 ,   HSA_ISA_INFO_GRID_MAX_DIM = 14 , HSA_ISA_INFO_GRID_MAX_SIZE = 16 , HSA_ISA_INFO_FBARRIER_MAX_SIZE = 17 }
	Instruction set architecture attributes. More...
enum	hsa_fp_type_t { HSA_FP_TYPE_16 = 1 , HSA_FP_TYPE_32 = 2 , HSA_FP_TYPE_64 = 4 }
	Floating-point types. More...
enum	hsa_flush_mode_t { HSA_FLUSH_MODE_FTZ = 1 , HSA_FLUSH_MODE_NON_FTZ = 2 }
	Flush to zero modes. More...
enum	hsa_round_method_t { HSA_ROUND_METHOD_SINGLE = 1 , HSA_ROUND_METHOD_DOUBLE = 2 }
	Round methods. More...
enum	hsa_wavefront_info_t { HSA_WAVEFRONT_INFO_SIZE = 0 }
	Wavefront attributes. More...

Functions
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.
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.
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).
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).
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.
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.
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.
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.
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.

Detailed Description

Typedef Documentation

hsa_isa_t

typedef struct hsa_isa_s hsa_isa_t

Instruction set architecture.

hsa_wavefront_t

typedef struct hsa_wavefront_s hsa_wavefront_t

Wavefront handle.

Enumeration Type Documentation

hsa_flush_mode_t

enum hsa_flush_mode_t

Flush to zero modes.

Enumerator
HSA_FLUSH_MODE_FTZ	Flush to zero.
HSA_FLUSH_MODE_NON_FTZ	Do not flush to zero.

Definition at line 3831 of file hsa.h.

hsa_fp_type_t

enum hsa_fp_type_t

Floating-point types.

Enumerator
HSA_FP_TYPE_16	16-bit floating-point type.
HSA_FP_TYPE_32	32-bit floating-point type.
HSA_FP_TYPE_64	64-bit floating-point type.

Definition at line 3812 of file hsa.h.

hsa_isa_info_t

enum hsa_isa_info_t

Instruction set architecture attributes.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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].
HSA_ISA_INFO_WORKGROUP_MAX_SIZE	Maximum total number of work-items in a work-group. The type of this attribute is uint32_t.
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.
HSA_ISA_INFO_GRID_MAX_SIZE	Maximum total number of work-items in a grid. The type of this attribute is uint64_t.
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.

Definition at line 3601 of file hsa.h.

hsa_round_method_t

enum hsa_round_method_t

Round methods.

Enumerator
HSA_ROUND_METHOD_SINGLE	Single round method.
HSA_ROUND_METHOD_DOUBLE	Double round method.

Definition at line 3846 of file hsa.h.

hsa_wavefront_info_t

enum hsa_wavefront_info_t

Wavefront attributes.

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.

Definition at line 3906 of file hsa.h.

Function Documentation

hsa_agent_iterate_isas()

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. If callback 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 to callback on every iteration. May be NULL.

Return values

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_isa_compatible()

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 values

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 or agent_isa are invalid.
HSA_STATUS_ERROR_INVALID_ARGUMENT	result is NULL.

hsa_isa_from_name()

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 values

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, or isa is NULL.

hsa_isa_get_exception_policies()

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 values

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, or mask is NULL.

hsa_isa_get_info()

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) in isa.
[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 of attribute, the behavior is undefined.

Return values

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, or value is NULL.

hsa_isa_get_info_alt()

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 of attribute, the behavior is undefined.

Return values

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, or value is NULL.

hsa_isa_get_round_method()

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 values

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, or flush_mode is not a valid flush to zero modifier, or round_method is NULL.

hsa_isa_iterate_wavefronts()

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. If callback 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 to callback on every iteration. May be NULL.

Return values

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_wavefront_get_info()

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 of attribute, the behavior is undefined.

Return values

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, or value is NULL.