Discovery Queries

Functions

Discovery Queries

Functions
amdsmi_status_t	amdsmi_get_socket_handles (uint32_t *socket_count, amdsmi_socket_handle *socket_handles)
	Get the list of socket handles in the system.
amdsmi_status_t	amdsmi_get_cpu_handles (uint32_t *cpu_count, amdsmi_processor_handle *processor_handles)
	Get the list of cpu handles in the system.
amdsmi_status_t	amdsmi_get_socket_info (amdsmi_socket_handle socket_handle, size_t len, char *name)
	Get information about the given socket.
amdsmi_status_t	amdsmi_get_processor_info (amdsmi_processor_handle processor_handle, size_t len, char *name)
	Get information about the given processor.
amdsmi_status_t	amdsmi_get_processor_count_from_handles (amdsmi_processor_handle *processor_handles, uint32_t *processor_count, uint32_t *nr_cpusockets, uint32_t *nr_cpucores, uint32_t *nr_gpus)
	Get respective processor counts from the processor handles.
amdsmi_status_t	amdsmi_get_processor_handles_by_type (amdsmi_socket_handle socket_handle, processor_type_t processor_type, amdsmi_processor_handle *processor_handles, uint32_t *processor_count)
	Get processor list as per processor type.
amdsmi_status_t	amdsmi_get_processor_handles (amdsmi_socket_handle socket_handle, uint32_t *processor_count, amdsmi_processor_handle *processor_handles)
	Get the list of the processor handles associated to a socket.
amdsmi_status_t	amdsmi_get_cpucore_handles (uint32_t *cores_count, amdsmi_processor_handle *processor_handles)
	Get the list of the cpu core handles in a system.
amdsmi_status_t	amdsmi_get_processor_type (amdsmi_processor_handle processor_handle, processor_type_t *processor_type)
	Get the processor type of the processor_handle.
amdsmi_status_t	amdsmi_get_processor_handle_from_bdf (amdsmi_bdf_t bdf, amdsmi_processor_handle *processor_handle)
	Get processor handle with the matching bdf.
amdsmi_status_t	amdsmi_get_gpu_device_bdf (amdsmi_processor_handle processor_handle, amdsmi_bdf_t *bdf)
	Returns BDF of the given device.
amdsmi_status_t	amdsmi_get_gpu_device_uuid (amdsmi_processor_handle processor_handle, unsigned int *uuid_length, char *uuid)
	Returns the UUID of the device.
amdsmi_status_t	amdsmi_get_gpu_enumeration_info (amdsmi_processor_handle processor_handle, amdsmi_enumeration_info_t *info)
	Returns the Enumeration information for the device.
amdsmi_status_t	amdsmi_get_cpu_affinity_with_scope (amdsmi_processor_handle processor_handle, uint32_t cpu_set_size, uint64_t *cpu_set, amdsmi_affinity_scope_t scope)
	Retrieves an array of uint64_t (sized to cpu_set_size) of bitmasks with the affinity within numa node or socket for the device.
amdsmi_status_t	amdsmi_get_gpu_virtualization_mode (amdsmi_processor_handle processor_handle, amdsmi_virtualization_mode_t *mode)
	Returns the virtualization mode for the target device.

Detailed Description

These functions provide discovery of the sockets.

Function Documentation

◆ amdsmi_get_socket_handles()

amdsmi_status_t amdsmi_get_socket_handles	(	uint32_t *	socket_count,
		amdsmi_socket_handle *	socket_handles
	)

Get the list of socket handles in the system.

Platform:

gpu_bm_linux

host

cpu_bm

guest_1vf

guest_mvf

guest_windows

Depends on what flag is passed to amdsmi_init. AMDSMI_INIT_AMD_GPUS returns sockets with AMD GPUS, and AMDSMI_INIT_AMD_GPUS | AMDSMI_INIT_AMD_CPUS returns sockets with either AMD GPUS or CPUS. The socket handles can be used to query the processor handles in that socket, which will be used in other APIs to get processor detail information or telemtries.

Parameters

[in,out]	socket_count	As input, the value passed through this parameter is the number of amdsmi_socket_handle that may be safely written to the memory pointed to by socket_handles. This is the limit on how many socket handles will be written to socket_handles. On return, socket_count will contain the number of socket handles written to socket_handles, or the number of socket handles that could have been written if enough memory had been provided. If socket_handles is NULL, as output, socket_count will contain how many sockets are available to read in the system.
[in,out]	socket_handles	A pointer to a block of memory to which the amdsmi_socket_handle values will be written. This value may be NULL. In this case, this function can be used to query how many sockets are available to read in the system.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_cpu_handles()

amdsmi_status_t amdsmi_get_cpu_handles	(	uint32_t *	cpu_count,
		amdsmi_processor_handle *	processor_handles
	)

Get the list of cpu handles in the system.

Platform:

cpu_bm

Depends on AMDSMI_INIT_AMD_CPUS flag passed to amdsmi_init. The processor handles can be used in other APIs to get processor detail information.

Parameters

[in,out]	cpu_count	As input, the value passed through this parameter is the number of amdsmi_processor_handle that may be safely written to the memory pointed to by processor_handles. This is the limit on how many processor handles will be written to processor_handles. On return, socket_count will contain the number of processor handles written to processor_handles, or the number of processor handles that could have been written if enough memory had been provided. If processor_handles is NULL, as output, cpu_count will contain how many processors are available to read in the system.
[in,out]	processor_handles	A pointer to a block of memory to which the amdsmi_processor_handle values will be written. This value may be NULL. In this case, this function can be used to query how many processors are available to read in the system.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_socket_info()

amdsmi_status_t amdsmi_get_socket_info	(	amdsmi_socket_handle	socket_handle,
		size_t	len,
		char *	name
	)

Get information about the given socket.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

This function retrieves socket information. The socket_handle must be provided to retrieve the Socket ID.

Parameters

[in]	socket_handle	a socket handle
[in]	len	the length of the caller provided buffer name.
[out]	name	The id of the socket.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_processor_info()

amdsmi_status_t amdsmi_get_processor_info	(	amdsmi_processor_handle	processor_handle,
		size_t	len,
		char *	name
	)

Get information about the given processor.

Platform:

cpu_bm

This function retrieves processor information. The processor_handle must be provided to retrieve the processor ID.

Parameters

[in]	processor_handle	a processor handle
[in]	len	the length of the caller provided buffer name.
[out]	name	The id of the processor.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_processor_count_from_handles()

amdsmi_status_t amdsmi_get_processor_count_from_handles	(	amdsmi_processor_handle *	processor_handles,
		uint32_t *	processor_count,
		uint32_t *	nr_cpusockets,
		uint32_t *	nr_cpucores,
		uint32_t *	nr_gpus
	)

Get respective processor counts from the processor handles.

Platform:

cpu_bm

This function retrieves respective processor counts information. The processor_handle must be provided to retrieve the processor ID.

Parameters

[in]	processor_handles	A pointer to a block of memory to which the amdsmi_processor_handle values will be written. This value may be NULL.
[in]	processor_count	total processor count per socket
[out]	nr_cpusockets	Total number of cpu sockets
[out]	nr_cpucores	Total number of cpu cores
[out]	nr_gpus	Total number of gpu devices

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_processor_handles_by_type()

amdsmi_status_t amdsmi_get_processor_handles_by_type	(	amdsmi_socket_handle	socket_handle,
		processor_type_t	processor_type,
		amdsmi_processor_handle *	processor_handles,
		uint32_t *	processor_count
	)

Get processor list as per processor type.

Platform:

cpu_bm

This function retrieves processor list as per the processor type from the total processor handles list. The list of processor_handles and processor type must be provided.

Parameters

[in]	socket_handle	socket handle
[in]	processor_type	processor type
[out]	processor_handles	list of processor handles as per processor type
[out]	processor_count	processor count as per processor type selected

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_processor_handles()

amdsmi_status_t amdsmi_get_processor_handles	(	amdsmi_socket_handle	socket_handle,
		uint32_t *	processor_count,
		amdsmi_processor_handle *	processor_handles
	)

Get the list of the processor handles associated to a socket.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

This function retrieves the processor handles of a socket. The socket_handle must be provided for the processor. A socket may have mulitple different type processors: An APU on a socket have both CPUs and GPUs. Currently, only AMD GPUs are supported.

Note

Sockets are not supported on the

Platform:

host.

The number of processor count is returned through processor_count if processor_handles is NULL. Then the number of processor_count can be pass as input to retrieval all processors on the socket to processor_handles.

Parameters

[in]	socket_handle	The socket to query
[in,out]	processor_count	As input, the value passed through this parameter is the number of amdsmi_processor_handle's that may be safely written to the memory pointed to by processor_handles. This is the limit on how many processor handles will be written to processor_handles. On return, processor_count will contain the number of processor handles written to processor_handles, or the number of processor handles that could have been written if enough memory had been provided. If processor_handles is NULL, as output, processor_count will contain how many processors are available to read for the socket.
[in,out]	processor_handles	A pointer to a block of memory to which the amdsmi_processor_handle values will be written. This value may be NULL. In this case, this function can be used to query how many processors are available to read.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_cpucore_handles()

amdsmi_status_t amdsmi_get_cpucore_handles	(	uint32_t *	cores_count,
		amdsmi_processor_handle *	processor_handles
	)

Get the list of the cpu core handles in a system.

Platform:

cpu_bm

This function retrieves the cpu core handles of a system.

Parameters

[in,out]	cores_count	As input, the value passed through this parameter is the number of amdsmi_processor_handle's that may be safely written to the memory pointed to by processor_handles. This is the limit on how many core handles will be written to processor_handles. On return, cores_count will contain the number of core processor handles written to processor_handles, or the number of core processor handles that could have been written if enough memory had been provided. If processor_handles is NULL, as output, processor_count will contain how many cpu cores are available to read in the system.
[in,out]	processor_handles	A pointer to a block of memory to which the amdsmi_processor_handle values will be written. This value may be NULL. In this case, this function can be used to query how many processors are available to read.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_processor_type()

amdsmi_status_t amdsmi_get_processor_type	(	amdsmi_processor_handle	processor_handle,
		processor_type_t *	processor_type
	)

Get the processor type of the processor_handle.

Platform:

gpu_bm_linux

host

cpu_bm

guest_1vf

guest_mvf

guest_windows

This function retrieves the processor type. A processor_handle must be provided for that processor.

Parameters

[in]	processor_handle	a processor handle
[out]	processor_type	a pointer to processor_type_t to which the processor type will be written. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_processor_handle_from_bdf()

amdsmi_status_t amdsmi_get_processor_handle_from_bdf	(	amdsmi_bdf_t	bdf,
		amdsmi_processor_handle *	processor_handle
	)

Get processor handle with the matching bdf.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Given bdf info bdf, this function will get the processor handle with the matching bdf.

Parameters

[in]	bdf	The bdf to match with corresponding processor handle.
[out]	processor_handle	processor handle with the matching bdf.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_gpu_device_bdf()

amdsmi_status_t amdsmi_get_gpu_device_bdf	(	amdsmi_processor_handle	processor_handle,
		amdsmi_bdf_t *	bdf
	)

Returns BDF of the given device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Parameters

[in]	processor_handle	Device which to query
[out]	bdf	Reference to BDF. Must be allocated by user.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_gpu_device_uuid()

amdsmi_status_t amdsmi_get_gpu_device_uuid	(	amdsmi_processor_handle	processor_handle,
		unsigned int *	uuid_length,
		char *	uuid
	)

Returns the UUID of the device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Parameters

[in]	processor_handle	Device which to query
[in,out]	uuid_length	Length of the uuid string. As input, must be equal or greater than AMDSMI_GPU_UUID_SIZE and be allocated by user. As output it is the length of the uuid string.
[out]	uuid	Pointer to string to store the UUID. Must be allocated by user.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_gpu_enumeration_info()

amdsmi_status_t amdsmi_get_gpu_enumeration_info	(	amdsmi_processor_handle	processor_handle,
		amdsmi_enumeration_info_t *	info
	)

Returns the Enumeration information for the device.

Platform:

gpu_bm_linux

guest_1vf

guest_mvf

This function returns Enumeration information of the corresponding processor_handle. It will return the render number, card number, HSA ID, HIP ID, and the HIP UUID.

Parameters

[in]	processor_handle	Device which to query
[out]	info	Reference to Enumeration information structure. Must be allocated by user.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_cpu_affinity_with_scope()

amdsmi_status_t amdsmi_get_cpu_affinity_with_scope	(	amdsmi_processor_handle	processor_handle,
		uint32_t	cpu_set_size,
		uint64_t *	cpu_set,
		amdsmi_affinity_scope_t	scope
	)

Retrieves an array of uint64_t (sized to cpu_set_size) of bitmasks with the affinity within numa node or socket for the device.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle, the size of the cpu_set array cpu_set_size, and a pointer to an array of int64_t cpu_set, and scope, this function will write the CPU affinity bitmask to the array pointed to by cpu_set.

User must allocate the enough memory for the cpu_set array. The size of the array is determined by the number of CPU cores in the system. As an example, if there are 2 CPUs and each has 112 cores, the size should be ceiling(2*112/64) = 4, where 64 is the bits of uint64_t. The function will write the CPU affinity bitmask to the array. For example, to describe the CPU cores 0-55,112-167, it will set the 0-55 and 112-167 bits to 1 and the reset of bits to 0 in the cpu_set array.

Parameters

[in]	processor_handle	a processor handle
[in]	cpu_set_size	The size of the cpu_set array that is safe to access
[in,out]	cpu_set	Array reference in which to return a bitmask of CPU cores that this processor affinities with.
[in]	scope	Scope for socket or numa affinity.

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_gpu_virtualization_mode()

amdsmi_status_t amdsmi_get_gpu_virtualization_mode	(	amdsmi_processor_handle	processor_handle,
		amdsmi_virtualization_mode_t *	mode
	)

Returns the virtualization mode for the target device.

Platform:

gpu_bm_linux

guest_1vf

host

The virtualization mode is detected and returned as an enum.

Parameters

[in]	processor_handle	The identifier of the given device.
[in,out]	mode	Reference to the enum representing virtualization mode. When zero, the virtualization mode is unknown When non-zero, the virtualization mode is detected

Returns

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail.