AMD SMI C/C++ functions

Contents

AMD SMI C/C++ functions#

AMD SMI library functions grouped by category. Each function returns an amdsmi_status_t status code. Some functions are not supported on all platforms.

Initialization and Shutdown#

amdsmi_status_t amdsmi_init(uint64_t init_flags)#

Initialize the AMD SMI library.

Platform:

gpu_bm_linux

host

cpu_bm

guest_1vf

guest_mvf

guest_windows

This function initializes the library and the internal data structures, including those corresponding to sources of information that SMI provides. Singleton Design, requires the same number of inits as shutdowns.

The init_flags decides which type of processor can be discovered by amdsmi_get_socket_handles(). 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. Both AMDSMI_INIT_AMD_GPUS and AMDSMI_INIT_AMD_CPUS flags are supported.

Parameters:

  • init_flags – [in] Bit flags that tell SMI how to initialize. Values of amdsmi_init_flags_t may be OR’d together and passed through init_flags to modify how AMDSMI initializes.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_shut_down(void)#

Shutdown the AMD SMI library.

Platform:

gpu_bm_linux

host

cpu_bm

guest_1vf

guest_mvf

guest_windows

This function shuts down the library and internal data structures and performs any necessary clean ups. Singleton Design, requires the same number of inits as shutdowns.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Discovery Queries#

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:

  • socket_count – [inout] 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.

  • socket_handles – [inout] 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_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:

  • socket_handle – [in] a socket handle

  • len – [in] the length of the caller provided buffer name.

  • name – [out] The id of the socket.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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 multiple different type processors: An APU on a socket have both CPUs and GPUs. Currently, only AMD GPUs are supported.

Platform:

host.

Platform:

host this function currently supports only AMD GPUs. To enumerate other devices, such as AMD NICs, use amdsmi_get_processor_handles_by_type().

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.

Note

Sockets are not supported on the

Note

On the

Parameters:

  • socket_handle – [in] The socket to query

  • processor_count – [inout] 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.

  • processor_handles – [inout] 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_status_t amdsmi_get_node_handle(amdsmi_processor_handle processor_handle, amdsmi_node_handle *node_handle)#

Get the node handle associated with processor handle.

Platform:

gpu_bm_linux

host

This function retrieves the node handle of a processor handler. The processor_handle must be provided for the processor. Currently, only AMD GPUs are supported.

Parameters:

  • processor_handle – [in] A pointer to a amdsmi_processor_handle, this is required to be OAM ID 0 otherwise the API will fail. OAM ID is sourced from amdsmi_get_gpu_asic_info API.

  • node_handle – [out] A pointer to a block of memory where amdsmi_node_handle will be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_processor_type(amdsmi_processor_handle processor_handle, amdsmi_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:

  • processor_handle – [in] a processor handle

  • processor_type – [out] a pointer to amdsmi_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_status_t amdsmi_get_processor_info(amdsmi_processor_handle processor_handle, size_t len, char *name)#

Get a string identifier for the given processor.

Platform:

gpu_bm_linux

cpu_bm

This function writes the processor’s index into name as a decimal string (for example “0”, “1”, “2”). The index is the processor’s zero-based position in the library’s processor list, the same order used by amdsmi_get_processor_handles. A valid processor_handle must be provided.

Parameters:

  • processor_handle – [in] a processor handle

  • len – [in] The length of the caller-provided buffer name.

  • name – [out] Buffer that receives the processor index as a decimal string. Must not be NULL.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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:

gpu_bm_linux

cpu_bm

This function classifies a list of processor handles and returns the per-type totals. Counts are derived purely from amdsmi_get_processor_type and do not require ENABLE_ESMI_LIB; on builds without ESMI, nr_cpusockets and nr_cpucores will be 0.

Parameters:

  • processor_handles – [in] A pointer to a block of memory to which the amdsmi_processor_handle values will be written. This value may be NULL.

  • processor_count – [in] total processor count per socket

  • nr_cpusockets – [out] Total number of cpu sockets

  • nr_cpucores – [out] Total number of cpu cores

  • nr_gpus – [out] Total number of gpu devices

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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

Returns a list of processor handles of the specified type in the system.

Platform:

gpu_bm_linux

host

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.

Note

This function fills the user-provided buffer with processor handles of the given type (e.g., GPU, NIC). The processor handles returned are used to instantiate the rest of processor queries in the library. If the buffer is not large enough, the call will fail.

Parameters:

  • socket_handle – [in] The socket to query.

  • processor_type – [in] The type of processor to query (see amdsmi_processor_type_t).

  • processor_handles – [out] Reference to list of processor handles returned by the library. Buffer must be allocated by user.

  • processor_count – [inout] As input, the size of the provided buffer. As output, number of processor handles in the buffer. Parameter must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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:

  • bdf – [in] The bdf to match with corresponding processor handle.

  • processor_handle – [out] processor handle with the matching bdf.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_device_bdf(amdsmi_processor_handle processor_handle, amdsmi_bdf_t *bdf)#

Returns BDF of the given GPU device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • bdf – [out] Reference to BDF. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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:

  • processor_handle – [in] Device which to query

  • uuid_length – [inout] 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.

  • uuid – [out] 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_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:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to Enumeration information structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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:

  • processor_handle – [in] a processor handle

  • cpu_set_size – [in] The size of the cpu_set array that is safe to access

  • cpu_set – [inout] Array reference in which to return a bitmask of CPU cores that this processor affinities with.

  • scope – [in] Scope for socket or numa affinity.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

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

host

guest_windows

The virtualization mode is detected and returned as an enum.

Parameters:

  • processor_handle – [in] The identifier of the given device.

  • mode – [inout] 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.

amdsmi_status_t amdsmi_get_nic_processor_handles(amdsmi_socket_handle socket_handle, uint32_t *processor_count, amdsmi_processor_handle *processor_handles)#

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

Platform:

gpu_bm_linux

host

This function retrieves the processor handles of a socket. The socket_handle must be provided for the processor.

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.

Note

Sockets are not supported on the

Parameters:

  • socket_handle – [in] The socket to query

  • processor_count – [inout] 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.

  • processor_handles – [inout] 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_status_t amdsmi_get_nic_device_bdf(amdsmi_processor_handle processor_handle, amdsmi_bdf_t *bdf)#

Returns BDF of the given NIC device.

Platform:

gpu_bm_linux

host

Parameters:

  • processor_handle – [in] Device which to query

  • bdf – [out] Reference to BDF. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Identifier Queries#

amdsmi_status_t amdsmi_get_gpu_id(amdsmi_processor_handle processor_handle, uint16_t *id)#

Get the device id associated with the device with provided device handler.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t id, this function will write the device id value to the uint64_t pointed to by id. This ID is an identification of the type of device, so calling this function for different devices will give the same value if they are kind of device. Consequently, this function should not be used to distinguish one device from another. amdsmi_get_gpu_bdf_id() should be used to get a unique identifier.

Parameters:

  • processor_handle – [in] a processor handle

  • id – [inout] a pointer to uint64_t to which the device id will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_revision(amdsmi_processor_handle processor_handle, uint16_t *revision)#

Get the device revision associated with the device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint16_t revision to which the revision id will be written

Parameters:

  • processor_handle – [in] a processor handle

  • revision – [out] a pointer to uint16_t to which the device revision will be written

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_vendor_name(amdsmi_processor_handle processor_handle, char *name, size_t len)#

Get the name string for a give vendor ID.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a pointer to a caller provided char buffer name, and a length of this buffer len, this function will write the name of the vendor (up to len characters) buffer name. The id may be a device vendor or subsystem vendor ID.

If the integer ID associated with the vendor is not found in one of the system files containing device name information (e.g. /usr/share/misc/pci.ids), then this function will return the hex vendor ID as a string. Updating the system name files can be accompplished with “sudo update-pciids”.

Note

AMDSMI_STATUS_INSUFFICIENT_SIZE is returned if len bytes is not large enough to hold the entire name. In this case, only len bytes will be written.

Parameters:

  • processor_handle – [in] a processor handle

  • name – [inout] a pointer to a caller provided char buffer to which the name will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

  • len – [in] the length of the caller provided buffer name.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_vram_vendor(amdsmi_processor_handle processor_handle, char *brand, uint32_t len)#

Get the vram vendor string of a device.

Deprecated:

This API is slated for removal in a future ROCm release; amdsmi_get_gpu_vram_info() should be used instead

Platform:

gpu_bm_linux

This function retrieves the vram vendor name given a processor handle processor_handle, a pointer to a caller provided char buffer brand, and a length of this buffer len, this function will write the vram vendor of the device (up to len characters) to the buffer brand.

If the vram vendor for the device is not found as one of the values contained within amdsmi_get_gpu_vram_vendor, then this function will return the string ‘unknown’ instead of the vram vendor.

Parameters:

  • processor_handle – [in] a processor handle

  • brand – [inout] a pointer to a caller provided char buffer to which the vram vendor will be written

  • len – [in] the length of the caller provided buffer brand.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_subsystem_id(amdsmi_processor_handle processor_handle, uint16_t *id)#

Get the subsystem device id associated with the device with provided processor handle.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t id, this function will write the subsystem device id value to the uint64_t pointed to by id.

Parameters:

  • processor_handle – [in] a processor handle

  • id – [inout] a pointer to uint64_t to which the subsystem device id will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_subsystem_name(amdsmi_processor_handle processor_handle, char *name, size_t len)#

Get the name string for the device subsystem.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a pointer to a caller provided char buffer name, and a length of this buffer len, this function will write the name of the device subsystem (up to len characters) to the buffer name.

If the integer ID associated with the sub-system is not found in one of the system files containing device name information (e.g. /usr/share/misc/pci.ids), then this function will return the hex sub-system ID as a string. Updating the system name files can be accompplished with “sudo update-pciids”.

Note

AMDSMI_STATUS_INSUFFICIENT_SIZE is returned if len bytes is not large enough to hold the entire name. In this case, only len bytes will be written.

Parameters:

  • processor_handle – [in] a processor handle

  • name – [inout] a pointer to a caller provided char buffer to which the name will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

  • len – [in] the length of the caller provided buffer name.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

PCIe Queries#

amdsmi_status_t amdsmi_get_gpu_pci_bandwidth(amdsmi_processor_handle processor_handle, amdsmi_pcie_bandwidth_t *bandwidth)#

Get the list of possible PCIe bandwidths that are available. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle and a pointer to a to an amdsmi_pcie_bandwidth_t structure bandwidth, this function will fill in bandwidth with the possible T/s values and associated number of lanes, and indication of the current selection.

Parameters:

  • processor_handle – [in] a processor handle

  • bandwidth – [inout] a pointer to a caller provided amdsmi_pcie_bandwidth_t structure to which the frequency information will be written

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_bdf_id(amdsmi_processor_handle processor_handle, uint64_t *bdfid)#

Get the unique PCI device identifier associated for a device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint64_t bdfid, this function will write the Bus/Device/Function PCI identifier (BDFID) associated with device processor_handle to the value pointed to by bdfid.

The format of bdfid will be as follows: 

BDFID = ((DOMAIN & 0xFFFFFFFF) << 32) | ((Partition & 0xF) << 28)
        | ((BUS & 0xFF) << 8) | ((DEVICE & 0x1F) <<3 )
        | (FUNCTION & 0x7)

Name

Field

KFD property

KFD -> PCIe ID (uint64_t)

Domain

[63:32]

“domain”

(DOMAIN & 0xFFFFFFFF) << 32

Partition id

[31:28]

“location id”

(LOCATION & 0xF0000000)

Reserved

[27:16]

“location id”

N/A

Bus

[15: 8]

“location id”

(LOCATION & 0xFF00)

Device

[ 7: 3]

“location id”

(LOCATION & 0xF8)

Function

[ 2: 0]

“location id”

(LOCATION & 0x7)

Note: In some devices, the partition ID may be stored in the function bits BDFID[2:0] instead of BDFID[31:28].

Note: For MI series devices, the function bits are only used to store the partition ID, but this modified BDF is internal to the ROCm stack. To the OS, partitions share the same BDF as the unpartitioned device and have function bits = 0, which can be verified through lspci.

Parameters:

  • processor_handle – [in] a processor handle

  • bdfid – [inout] a pointer to uint64_t to which the device bdfid value will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_topo_numa_affinity(amdsmi_processor_handle processor_handle, int32_t *numa_node)#

Get the NUMA node associated with a device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a int32_t numa_node, this function will retrieve the NUMA node value associated with device processor_handle and store the value at location pointed to by numa_node.

Parameters:

  • processor_handle – [in] a processor handle

  • numa_node – [inout] pointer to location where NUMA node value will be written. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_pci_throughput(amdsmi_processor_handle processor_handle, uint64_t *sent, uint64_t *received, uint64_t *max_pkt_sz)#

Get PCIe traffic information. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Give a processor handle processor_handle and pointers to a uint64_t’s, sent, received and max_pkt_sz, this function will write the number of bytes sent and received in 1 second to sent and received, respectively. The maximum possible packet size will be written to max_pkt_sz.

Parameters:

  • processor_handle – [in] a processor handle

  • sent – [inout] a pointer to uint64_t to which the number of bytes sent will be written in 1 second. If pointer is NULL, it will be ignored.

  • received – [inout] a pointer to uint64_t to which the number of bytes received will be written. If pointer is NULL, it will be ignored.

  • max_pkt_sz – [inout] a pointer to uint64_t to which the maximum packet size will be written. If pointer is NULL, it will be ignored.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_pci_replay_counter(amdsmi_processor_handle processor_handle, uint64_t *counter)#

Get PCIe replay counter.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint64_t counter, this function will write the sum of the number of NAK’s received by the GPU and the NAK’s generated by the GPU to memory pointed to by counter.

Parameters:

  • processor_handle – [in] a processor handle

  • counter – [inout] a pointer to uint64_t to which the sum of the NAK’s received and generated by the GPU is written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

PCIe Control#

amdsmi_status_t amdsmi_set_gpu_pci_bandwidth(amdsmi_processor_handle processor_handle, uint64_t bw_bitmask)#

Control the set of allowed PCIe bandwidths that can be used. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a 64 bit bitmask bw_bitmask, this function will limit the set of allowable bandwidths. If a bit in bw_bitmask has a value of 1, then the frequency (as ordered in an amdsmi_frequencies_t returned by :: amdsmi_get_clk_freq()) corresponding to that bit index will be allowed.

This function will change the performance level to AMDSMI_DEV_PERF_LEVEL_MANUAL in order to modify the set of allowable band_widths. Caller will need to set to AMDSMI_DEV_PERF_LEVEL_AUTO in order to get back to default state.

All bits with indices greater than or equal to the value of the amdsmi_frequencies_t::num_supported field of amdsmi_pcie_bandwidth_t will be ignored.

Note

This function requires admin/sudo privileges

Parameters:
Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Power Queries#

amdsmi_status_t amdsmi_get_energy_count(amdsmi_processor_handle processor_handle, uint64_t *energy_accumulator, float *counter_resolution, uint64_t *timestamp)#

Get the energy accumulator counter of the processor with provided processor handle. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a pointer to a uint64_t energy_accumulator, and a pointer to a uint64_t timestamp, this function will write amount of energy consumed to the uint64_t pointed to by energy_accumulator, and the timestamp to the uint64_t pointed to by timestamp. This function accumulates all energy consumed.

Parameters:

  • processor_handle – [in] a processor handle

  • energy_accumulator – [inout] a pointer to uint64_t to which the energy counter will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

  • counter_resolution – [inout] resolution of the counter energy_accumulator in micro Joules

  • timestamp – [inout] a pointer to uint64_t to which the timestamp will be written. Resolution: 1 ns.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Power Control#

amdsmi_status_t amdsmi_set_power_cap(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, uint64_t cap)#

Set the maximum gpu power cap value. It is not supported on virtual machine guest.

Platform:

host

gpu_bm_linux

guest_1vf

Set the power cap to the provided value cap. cap must be between the minimum and maximum power cap values set by the system, which can be obtained from ::amdsmi_dev_power_cap_range_get.

Parameters:

  • processor_handle – [in] A processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a processor has more than one sensor, it could be greater than 0.

  • cap – [in] a uint64_t that indicates the desired power cap. The cap value must be greater than 0.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_power_profile(amdsmi_processor_handle processor_handle, uint32_t reserved, amdsmi_power_profile_preset_masks_t profile)#

Set the power performance profile. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

This function will attempt to set the current profile to the provided profile, given a processor handle processor_handle and a profile. The provided profile must be one of the currently supported profiles, as indicated by a call to :: amdsmi_get_gpu_power_profile_presets()

Parameters:

  • processor_handle – [in] a processor handle

  • reserved – [in] Not currently used. Set to 0.

  • profile – [in] a amdsmi_power_profile_preset_masks_t that hold the mask of the desired new power profile

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_supported_power_cap(amdsmi_processor_handle processor_handle, uint32_t *sensor_count, uint32_t *sensor_inds, amdsmi_power_cap_type_t *sensor_types)#

Query the supported power cap sensors and their types for a device.

Platform:

gpu_bm_linux

host

This function returns the list of supported power cap sensors for the given device, including their sensor indices and types (e.g., PPT0, PPT1).

Parameters:

  • processor_handle – [in] A processor handle.

  • sensor_count – [out] Pointer to a uint32_t that will be set to the number of supported sensors.

  • sensor_inds – [out] Pointer to an array of uint32_t to be filled with sensor indices. The array must be allocated by the caller with enough space.

  • sensor_types – [out] Pointer to an array of amdsmi_power_cap_type_t to be filled with sensor types. The array must be allocated by the caller with enough space.

Returns:

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

amdsmi_status_t amdsmi_get_cpu_socket_power(amdsmi_processor_handle processor_handle, uint32_t *ppower)#

Get the socket power.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • ppower – [out] - Input buffer to return socket power in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_power_cap(amdsmi_processor_handle processor_handle, uint32_t *pcap)#

Get the socket power cap.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • pcap – [out] - Input buffer to return power cap in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_power_cap_max(amdsmi_processor_handle processor_handle, uint32_t *pmax)#

Get the maximum power cap value for a given socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • pmax – [out] - Input buffer to return maximum power limit value in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_pwr_svi_telemetry_all_rails(amdsmi_processor_handle processor_handle, uint32_t *power)#

Get the SVI based power telemetry for all rails.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • power – [inout] - Input buffer to return svi based power value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_socket_power_cap(amdsmi_processor_handle processor_handle, uint32_t pcap)#

Set the power cap value for a given socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • pcap – [in] - Input power limit value in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_pwr_efficiency_mode(amdsmi_processor_handle processor_handle, uint8_t power_efficiency_mode, uint32_t *utilization, uint32_t *ppt_limit)#

Set the power efficiency profile policy.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to configure

  • power_efficiency_mode – [in] - power efficiency mode to be set

  • utilization – [inout] - pointer to store utilization for balanced core modes (%)

  • ppt_limit – [inout] - pointer to PPT (Package Power Tracking) limit value in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_pwr_efficiency_mode(amdsmi_processor_handle processor_handle, uint32_t *power_efficiency_mode, uint32_t *utilization, uint32_t *ppt_limit)#

Get the power efficiency profile policy.

This function retrieves the current power efficiency mode, utility value, and PPT (Package Power Tracking) limit for a given processor socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • power_efficiency_mode – [out] - pointer to store current power efficiency mode

  • utilization – [out] - pointer to store utilization for balanced core modes (%)

  • ppt_limit – [out] - pointer to store PPT (Package Power Tracking) limit value in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_core_ccd_power(amdsmi_processor_handle processor_handle, uint32_t *power)#

Read CCD (Core Complex Die) power consumption.

This function reads the power consumption of a specific CCD within a CPU socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu core which to query

  • power – [out] - Input buffer to store power consumption in milliwatts (mW)

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on successful register read, non-zero on failure

Memory Queries#

amdsmi_status_t amdsmi_get_gpu_memory_total(amdsmi_processor_handle processor_handle, amdsmi_memory_type_t mem_type, uint64_t *total)#

Get the total amount of memory that exists.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a type of memory mem_type, and a pointer to a uint64_t total, this function will write the total amount of mem_type memory that exists to the location pointed to by total.

Note

Sum of the process memory is not expected to be the total memory usage.

Parameters:

  • processor_handle – [in] a processor handle

  • mem_type – [in] The type of memory for which the total amount will be found

  • total – [inout] a pointer to uint64_t to which the total amount of memory will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_memory_usage(amdsmi_processor_handle processor_handle, amdsmi_memory_type_t mem_type, uint64_t *used)#

Get the current memory usage.

Platform:

gpu_bm_linux

This function will write the amount of mem_type memory that that is currently being used to the location pointed to by used.

Note

Sum of the process memory is not expected to be the total memory usage.

Parameters:

  • processor_handle – [in] a processor handle

  • mem_type – [in] The type of memory for which the amount being used will be found

  • used – [inout] a pointer to uint64_t to which the amount of memory currently being used will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_bad_page_info(amdsmi_processor_handle processor_handle, uint32_t *num_pages, amdsmi_retired_page_record_t *info)#

Get the bad pages of a processor. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

This call will query the device processor_handle for the number of bad pages (written to num_pages address). The results are written to address held by the info pointer. The first call to this API returns the number of bad pages which should be used to allocate the buffer that should contain the bad page records.

Parameters:

  • processor_handle – [in] a processor handle

  • num_pages – [out] Number of bad page records.

  • info – [out] The results will be written to the amdsmi_retired_page_record_t pointer.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_bad_page_threshold(amdsmi_processor_handle processor_handle, uint32_t *threshold)#

Get the bad pages threshold of a processor. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

This call will query the device processor_handle for the threshold of bad pages (written to threshold address).

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

  • threshold – [out] of bad page count.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_gpu_validate_ras_eeprom(amdsmi_processor_handle processor_handle)#

Verify the checksum of RAS EEPROM. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

This call will verify the device processor_handle for the checksum of RAS EEPROM.

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success AMDSMI_STATUS_CORRUPTED_EEPROM on the device’s EEPROM corruption others on fail

amdsmi_status_t amdsmi_get_gpu_ras_block_features_enabled(amdsmi_processor_handle processor_handle, amdsmi_gpu_block_t block, amdsmi_ras_err_state_t *state)#

Returns if RAS features are enabled or disabled for given block. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, this function queries the state of RAS features for a specific block block. Result will be written to address held by pointer state.

Parameters:

  • processor_handle – [in] Device handle which to query

  • block – [in] Block which to query

  • state – [inout] A pointer to amdsmi_ras_err_state_t to which the state of block will be written. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_memory_reserved_pages(amdsmi_processor_handle processor_handle, uint32_t *num_pages, amdsmi_retired_page_record_t *records)#

Get information about reserved (“retired”) memory pages. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, this function returns retired page information records corresponding to the device with the provided processor handle processor_handle. The number of retired page records is returned through num_pages. records may be NULL on input. In this case, the number of records available for retrieval will be returned through num_pages.

Parameters:

  • processor_handle – [in] a processor handle

  • num_pages – [inout] a pointer to a uint32. As input, the value passed through this parameter is the number of amdsmi_retired_page_record_t’s that may be safely written to the memory pointed to by records. This is the limit on how many records will be written to records. On return, num_pages will contain the number of records written to records, or the number of records that could have been written if enough memory had been provided. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

  • records – [inout] A pointer to a block of memory to which the amdsmi_retired_page_record_t values will be written. This value may be NULL. In this case, this function can be used to query how many records are available to read.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Physical State Queries#

amdsmi_status_t amdsmi_get_gpu_fan_rpms(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, int64_t *speed)#

Get the fan speed in RPMs of the device with the specified processor handle and 0-based sensor index. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t speed, this function will write the current fan speed in RPMs to the uint32_t pointed to by speed

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0.

  • speed – [inout] a pointer to uint32_t to which the speed will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_fan_speed(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, int64_t *speed)#

Get the fan speed for the specified device as a value relative to the maximum fan speed. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t speed, this function will write the current fan speed (a value between 0 and the maximum fan speed) to the uint32_t pointed to by speed. For legacy hwmon GPUs the maximum is AMDSMI_MAX_FAN_SPEED (255). For GPUs with the gpu_od sysfs interface, use amdsmi_get_gpu_fan_speed_max() to query the actual maximum

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0.

  • speed – [inout] a pointer to uint32_t to which the speed will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_fan_speed_max(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, uint64_t *max_speed)#

Get the max. fan speed of the device with provided processor handle. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t max_speed, this function will write the maximum fan speed possible to the uint32_t pointed to by max_speed. For legacy hwmon GPUs this is AMDSMI_MAX_FAN_SPEED (255). For GPUs with the gpu_od sysfs interface, the maximum is read from the OD_RANGE section of the fan_minimum_pwm sysfs file (e.g. 100)

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0.

  • max_speed – [inout] a pointer to uint32_t to which the maximum speed will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_cache_info(amdsmi_processor_handle processor_handle, amdsmi_gpu_cache_info_t *info)#

Returns gpu cache info.

Platform:

gpu_bm_linux

host

Parameters:

  • processor_handle – [in] PF of a processor for which to query

  • info – [out] reference to the cache info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_volt_metric(amdsmi_processor_handle processor_handle, amdsmi_voltage_type_t sensor_type, amdsmi_voltage_metric_t metric, int64_t *voltage)#

Get the voltage metric value for the specified metric, from the specified voltage sensor on the specified device. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a sensor type sensor_type, a amdsmi_voltage_metric_t metric and a pointer to an int64_t voltage, this function will write the value of the metric indicated by metric and sensor_type to the memory location voltage.

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_type – [in] part of device from which voltage should be obtained. This should come from the enum amdsmi_voltage_type_t

  • metric – [in] enum indicated which voltage value should be retrieved

  • voltage – [inout] a pointer to int64_t to which the voltage will be written, in millivolts. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Physical State Control#

amdsmi_status_t amdsmi_reset_gpu_fan(amdsmi_processor_handle processor_handle, uint32_t sensor_ind)#

Reset the fan to automatic driver control. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

This function returns control of the fan to the system. For GPUs with the gpu_od sysfs interface, this writes the OD_RANGE minimum value to fan_minimum_pwm and commits the change

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_fan_speed(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, uint64_t speed)#

Set the fan speed for the specified device with the provided speed, in RPMs. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a integer value indicating speed speed, this function will attempt to set the fan speed to speed. An error will be returned if the specified speed is outside the allowable range for the device. For legacy hwmon GPUs the range is 0-255. For GPUs with the gpu_od sysfs interface, the valid range is determined dynamically from the OD_RANGE (e.g. 20-100).

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0.

  • speed – [in] the speed to which the function will attempt to set the fan

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Clock, Power and Performance Queries#

amdsmi_status_t amdsmi_get_gpu_busy_percent(amdsmi_processor_handle processor_handle, uint32_t *gpu_busy_percent)#

Get GPU busy percent from gpu_busy_percent sysfs file.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, this function returns GPU busy percentage.

Parameters:

  • processor_handle – [in] a processor handle

  • gpu_busy_percent – [inout] Direct output from the gpu_busy_percent sysfs file

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_utilization_count(amdsmi_processor_handle processor_handle, amdsmi_utilization_counter_t utilization_counters[], uint32_t count, uint64_t *timestamp)#

Get coarse grain utilization counter of the specified device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, the array of the utilization counters, the size of the array, this function returns the coarse grain utilization counters and timestamp. The counter is the accumulated percentages. Every milliseconds the firmware calculates % busy count and then accumulates that value in the counter. This provides minimally invasive coarse grain GPU usage information.

If the function returns AMDSMI_STATUS_SUCCESS, the counter will be set in the value field of the amdsmi_utilization_counter_t.

Parameters:

  • processor_handle – [in] a processor handle

  • utilization_counters – [inout] Multiple utilization counters can be retrieved with a single call. The caller must allocate enough space to the utilization_counters array. The caller also needs to set valid AMDSMI_UTILIZATION_COUNTER_TYPE type for each element of the array. AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

  • count – [in] The size of utilization_counters array.

  • timestamp – [inout] The timestamp when the counter is retrieved. Resolution: 1 ns.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_perf_level(amdsmi_processor_handle processor_handle, amdsmi_dev_perf_level_t *perf)#

Get the performance level of the device. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

This function will write the amdsmi_dev_perf_level_t to the uint32_t pointed to by perf, for a given processor handle processor_handle and a pointer to a uint32_t perf.

Parameters:

  • processor_handle – [in] a processor handle

  • perf – [inout] a pointer to amdsmi_dev_perf_level_t to which the performance level will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_perf_determinism_mode(amdsmi_processor_handle processor_handle, uint64_t clkvalue)#

Enter performance determinism mode with provided processor handle. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and clkvalue this function will enable performance determinism mode, which enforces a GFXCLK frequency SoftMax limit per GPU set by the user. This prevents the GFXCLK PLL from stretching when running the same workload on different GPUS, making performance variation minimal. This call will result in the performance level amdsmi_dev_perf_level_t of the device being AMDSMI_DEV_PERF_LEVEL_DETERMINISM.

Parameters:

  • processor_handle – [in] a processor handle

  • clkvalue – [in] Softmax value for GFXCLK in MHz.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_overdrive_level(amdsmi_processor_handle processor_handle, uint32_t *od)#

Get the overdrive percent associated with the device with provided processor handle. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t od, this function will write the overdrive percentage to the uint32_t pointed to by od

Parameters:

  • processor_handle – [in] a processor handle

  • od – [inout] a pointer to uint32_t to which the overdrive percentage will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_mem_overdrive_level(amdsmi_processor_handle processor_handle, uint32_t *od)#

Get the GPU memory clock overdrive percent associated with the device with provided processor handle. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a uint32_t od, this function will write the overdrive percentage to the uint32_t pointed to by od

Parameters:

  • processor_handle – [in] a processor handle

  • od – [inout] a pointer to uint32_t to which the GPU memory clock overdrive percentage will be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_clk_freq(amdsmi_processor_handle processor_handle, amdsmi_clk_type_t clk_type, amdsmi_frequencies_t *f)#

Get the list of possible system clock speeds of device for a specified clock type. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a clock type clk_type, and a pointer to a to an amdsmi_frequencies_t structure f, this function will fill in f with the possible clock speeds, and indication of the current clock speed selection.

Parameters:

  • processor_handle – [in] a processor handle

  • clk_type – [in] the type of clock for which the frequency is desired

  • f – [inout] a pointer to a caller provided amdsmi_frequencies_t structure to which the frequency information will be written. Frequency values are in Hz.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_reset_gpu(amdsmi_processor_handle processor_handle)#

Triggers a chain that resets all GPUs. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle, this function will reset the GPU

Note

After this function returns, the caller must wait a few seconds before calling any other AMD SMI API functions to allow the GPU reset to complete. Calling other APIs too soon may result in AMDSMI_STATUS_BUSY or undefined behavior.

Parameters:

  • processor_handle – [in] a processor handle

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_od_volt_info(amdsmi_processor_handle processor_handle, amdsmi_od_volt_freq_data_t *odv)#

This function retrieves the overdrive GFX & MCLK information. If valid for the GPU it will also populate the voltage curve data. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a amdsmi_od_volt_freq_data_t structure odv, this function will populate odv. See amdsmi_od_volt_freq_data_t for more details.

Parameters:
Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_metrics_header_info(amdsmi_processor_handle processor_handle, amd_metrics_table_header_t *header_value)#

Get the ‘metrics_header_info’ from the GPU metrics associated with the device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a amd_metrics_table_header_t in which the ‘metrics_header_info’ will stored

Parameters:

  • processor_handle – [in] Device which to query

  • header_value – [inout] a pointer to amd_metrics_table_header_t to which the device gpu metric unit will be stored

Return values:

AMDSMI_STATUS_SUCCESS – is returned upon successful call. AMDSMI_STATUS_NOT_SUPPORTED is returned in case the metric unit does not exist for the given device

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_get_gpu_metrics_info(amdsmi_processor_handle processor_handle, amdsmi_gpu_metrics_t *pgpu_metrics)#

This function retrieves the gpu metrics information. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a amdsmi_gpu_metrics_t structure pgpu_metrics, this function will populate pgpu_metrics. See amdsmi_gpu_metrics_t for more details.

APU Metrics: When APU-specific metrics are available (APU metrics table v2.4 or v3.0), pgpu_metrics->apu_metrics will point to thread-local library-owned storage. This pointer is invalidated by ANY subsequent call to amdsmi_get_gpu_metrics_info or amdsmi_get_gpu_partition_metrics_info on the same thread, even for different devices. Callers must copy the entire amdsmi_apu_metrics_t structure immediately after the call to preserve the data. For non-APU devices, pgpu_metrics->apu_metrics will be nullptr.

Parameters:

  • processor_handle – [in] a processor handle

  • pgpu_metrics – [inout] a pointer to an amdsmi_gpu_metrics_t structure If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_partition_metrics_info(amdsmi_processor_handle processor_handle, amdsmi_gpu_metrics_t *pgpu_metrics)#

This function retrieves the partition metrics information.

Platform:

gpu_bm_linux

guest_1vf

Given a processor handle processor_handle and a pointer to a amdsmi_gpu_metrics_t structure pgpu_metrics, this function will populate pgpu_metrics. See amdsmi_gpu_metrics_t for more details.

APU Metrics: When APU-specific metrics are available (APU metrics table v2.4 or v3.0), pgpu_metrics->apu_metrics will point to thread-local library-owned storage. This pointer is invalidated by ANY subsequent call to amdsmi_get_gpu_metrics_info or amdsmi_get_gpu_partition_metrics_info on the same thread, even for different devices. Callers must copy the entire amdsmi_apu_metrics_t structure immediately after the call to preserve the data. For non-APU devices, pgpu_metrics->apu_metrics will be nullptr.

Parameters:

  • processor_handle – [in] a processor handle

  • pgpu_metrics – [inout] a pointer to an amdsmi_gpu_metrics_t structure If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_pm_metrics_info(amdsmi_processor_handle processor_handle, amdsmi_name_value_t **pm_metrics, uint32_t *num_of_metrics)#

Get the pm metrics table with provided device index.

Platform:

gpu_bm_linux

Given a device handle processor_handle, pm_metrics pointer, and num_of_metrics pointer, this function will write the pm metrics name value pair to the array at pm_metrics and the number of metrics retrieved to num_of_metrics Note: the library allocated memory for pm_metrics, and user must call free(pm_metrics) to free it after use.

Parameters:

  • processor_handle – [in] a processor handle

  • pm_metrics – [inout] A pointerto an array to hold multiple PM metrics. On success, the library will allocate memory of pm_metrics and write metrics to this array. The caller must free this memory after usage to avoid memory leak.

  • num_of_metrics – [inout] a pointer to uint32_t to which the number of metrics is allocated for pm_metrics array as input, and the number of metrics retrieved as output. If this parameter is NULL, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function with the given arguments

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_get_gpu_reg_table_info(amdsmi_processor_handle processor_handle, amdsmi_reg_type_t reg_type, amdsmi_name_value_t **reg_metrics, uint32_t *num_of_metrics)#

Get the register metrics table with provided device index and register type.

Platform:

gpu_bm_linux

Given a device handle processor_handle, reg_type, reg_metrics pointer, and num_of_metrics pointer, this function will write the register metrics name value pair to the array at reg_metrics and the number of metrics retrieved to num_of_metrics Note: the library allocated memory for reg_metrics, and user must call free(reg_metrics) to free it after use.

Parameters:

  • processor_handle – [in] a processor handle

  • reg_type – [in] The register type

  • reg_metrics – [inout] A pointerto an array to hold multiple register metrics. On success, the library will allocate memory of reg_metrics and write metrics to this array. The caller must free this memory after usage to avoid memory leak.

  • num_of_metrics – [inout] a pointer to uint32_t to which the number of metrics is allocated for reg_metrics array as input, and the number of metrics retrieved as output. If this parameter is NULL, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function with the given arguments

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_set_gpu_clk_range(amdsmi_processor_handle processor_handle, uint64_t minclkvalue, uint64_t maxclkvalue, amdsmi_clk_type_t clkType)#

This function sets the clock range information. It is not supported on virtual machine guest.

Deprecated:

amdsmi_set_gpu_clk_limit() should be used, with an interface that set the min_value and then max_value.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a minimum clock value minclkvalue, a maximum clock value maxclkvalue and a clock type clkType this function will set the sclk|mclk range

Parameters:

  • processor_handle – [in] a processor handle

  • minclkvalue – [in] value to apply to the clock range. Frequency values are in MHz.

  • maxclkvalue – [in] value to apply to the clock range. Frequency values are in MHz.

  • clkType – [in] AMDSMI_CLK_TYPE_SYS | AMDSMI_CLK_TYPE_MEM range type

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_clk_limit(amdsmi_processor_handle processor_handle, amdsmi_clk_type_t clk_type, amdsmi_clk_limit_type_t limit_type, uint64_t clk_value)#

This function sets the clock sets the clock min/max level.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a clock type clk_type, a value clk_value needs to be set, and the level indicates min or max clock you want to set, this function the clock limit.

Parameters:

  • processor_handle – [in] a processor handle

  • clk_type – [in] AMDSMI_CLK_TYPE_SYS, AMDSMI_CLK_TYPE_MEM and so on

  • limit_type – [in] AMDSMI_FREQ_IND_MIN|AMDSMI_FREQ_IND_MAX to set the minimum (0) or maximum (1) speed.

  • clk_value – [in] value to apply to. Frequency values are in MHz.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_od_clk_info(amdsmi_processor_handle processor_handle, amdsmi_freq_ind_t level, uint64_t clkvalue, amdsmi_clk_type_t clkType)#

This function sets the clock frequency information. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a frequency level level, a clock value clkvalue and a clock type clkType this function will set the sclk|mclk range

Parameters:

  • processor_handle – [in] a processor handle

  • level – [in] AMDSMI_FREQ_IND_MIN|AMDSMI_FREQ_IND_MAX to set the minimum (0) or maximum (1) speed.

  • clkvalue – [in] value to apply to the clock range. Frequency values are in MHz.

  • clkType – [in] AMDSMI_CLK_TYPE_SYS | AMDSMI_CLK_TYPE_MEM range type

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_od_volt_info(amdsmi_processor_handle processor_handle, uint32_t vpoint, uint64_t clkvalue, uint64_t voltvalue)#

This function sets 1 of the 3 voltage curve points. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a voltage point vpoint and a voltage value voltvalue this function will set voltage curve point

Parameters:

  • processor_handle – [in] a processor handle

  • vpoint – [in] voltage point [0|1|2] on the voltage curve

  • clkvalue – [in] clock value component of voltage curve point. Frequency values are in MHz.

  • voltvalue – [in] voltage value component of voltage curve point. Voltage is in mV.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_od_volt_curve_regions(amdsmi_processor_handle processor_handle, uint32_t *num_regions, amdsmi_freq_volt_region_t *buffer)#

This function will retrieve the current valid regions in the frequency/voltage space. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a pointer to an unsigned integer num_regions and a buffer of amdsmi_freq_volt_region_t structures, buffer, this function will populate buffer with the current frequency-volt space regions. The caller should assign buffer to memory that can be written to by this function. The caller should also indicate the number of amdsmi_freq_volt_region_t structures that can safely be written to buffer in num_regions.

The number of regions to expect this function provide (num_regions) can be obtained by calling :: amdsmi_get_gpu_od_volt_info().

Parameters:
Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_power_profile_presets(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, amdsmi_power_profile_status_t *status)#

Get the list of available preset power profiles and an indication of which profile is currently active. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer to a amdsmi_power_profile_status_t status, this function will set the bits of the amdsmi_power_profile_status_t.available_profiles bit field of status to 1 if the profile corresponding to the respective amdsmi_power_profile_preset_masks_t profiles are enabled. For example, if both the VIDEO and VR power profiles are available selections, then AMDSMI_PWR_PROF_PRST_VIDEO_MASK AND’ed with amdsmi_power_profile_status_t.available_profiles will be non-zero as will AMDSMI_PWR_PROF_PRST_VR_MASK AND’ed with amdsmi_power_profile_status_t.available_profiles. Additionally, amdsmi_power_profile_status_t.current will be set to the amdsmi_power_profile_preset_masks_t of the profile that is currently active.

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_ind – [in] a 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0.

  • status – [inout] a pointer to amdsmi_power_profile_status_t that will be populated by a call to this function If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Clock, Power and Performance Control#

amdsmi_status_t amdsmi_set_gpu_perf_level(amdsmi_processor_handle processor_handle, amdsmi_dev_perf_level_t perf_lvl)#

Set the PowerPlay performance level associated with the device with provided processor handle with the provided value. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and an amdsmi_dev_perf_level_t perf_level, this function will set the PowerPlay performance level for the device to the value perf_lvl.

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

  • perf_lvl – [in] the value to which the performance level should be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_overdrive_level(amdsmi_processor_handle processor_handle, uint32_t od)#

Set the overdrive percent associated with the device with provided processor handle with the provided value. See details for WARNING. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and an overdrive level od, this function will set the overdrive level for the device to the value od. The overdrive level is an integer value between 0 and 20, inclusive, which represents the overdrive percentage; e.g., a value of 5 specifies an overclocking of 5%.

The overdrive level is specific to the gpu system clock.

The overdrive level is the percentage above the maximum Performance Level to which overclocking will be limited. The overclocking percentage does not apply to clock speeds other than the maximum. This percentage is limited to 20%.

******WARNING****** Operating your AMD GPU outside of official AMD specifications or outside of factory settings, including but not limited to the conducting of overclocking (including use of this overclocking software, even if such software has been directly or indirectly provided by AMD or otherwise affiliated in any way with AMD), may cause damage to your AMD GPU, system components and/or result in system failure, as well as cause other problems. DAMAGES CAUSED BY USE OF YOUR AMD GPU OUTSIDE OF OFFICIAL AMD SPECIFICATIONS OR OUTSIDE OF FACTORY SETTINGS ARE NOT COVERED UNDER ANY AMD PRODUCT WARRANTY AND MAY NOT BE COVERED BY YOUR BOARD OR SYSTEM MANUFACTURER’S WARRANTY. Please use this utility with caution.

Parameters:

  • processor_handle – [in] a processor handle

  • od – [in] the value to which the overdrive level should be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_clk_freq(amdsmi_processor_handle processor_handle, amdsmi_clk_type_t clk_type, uint64_t freq_bitmask)#

Control the set of allowed frequencies that can be used for the specified clock. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a clock type clk_type, and a 64 bit bitmask freq_bitmask, this function will limit the set of allowable frequencies. If a bit in freq_bitmask has a value of 1, then the frequency (as ordered in an amdsmi_frequencies_t returned by amdsmi_get_clk_freq()) corresponding to that bit index will be allowed.

This function will change the performance level to AMDSMI_DEV_PERF_LEVEL_MANUAL in order to modify the set of allowable frequencies. Caller will need to set to AMDSMI_DEV_PERF_LEVEL_AUTO in order to get back to default state.

All bits with indices greater than or equal to amdsmi_frequencies_t::num_supported will be ignored.

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

  • clk_type – [in] the type of clock for which the set of frequencies will be modified

  • freq_bitmask – [in] A bitmask indicating the indices of the frequencies that are to be enabled (1) and disabled (0). Only the lowest amdsmi_frequencies_t.num_supported bits of this mask are relevant.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_soc_pstate(amdsmi_processor_handle processor_handle, amdsmi_dpm_policy_t *policy)#

Get the soc pstate policy for the processor.

Platform:

gpu_bm_linux

guest_1vf

host

Given a processor handle processor_handle, this function will write current soc pstate policy settings to policy. All the processors at the same socket will have the same policy.

Parameters:

  • processor_handle – [in] a processor handle

  • policy – [inout] the soc pstate policy for this processor. 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_status_t amdsmi_set_soc_pstate(amdsmi_processor_handle processor_handle, uint32_t policy_id)#

Set the soc pstate policy for the processor.

Platform:

gpu_bm_linux

guest_1vf

host

Given a processor handle processor_handle and a soc pstate policy policy_id, this function will set the soc pstate policy for this processor. All the processors at the same socket will be set to the same policy.

Platform:

gpu_bm_linux

Note

This function requires admin/sudo privileges on

Parameters:
Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_xgmi_plpd(amdsmi_processor_handle processor_handle, amdsmi_dpm_policy_t *xgmi_plpd)#

Get the xgmi per-link power down policy parameter for the processor.

Platform:

gpu_bm_linux

guest_1vf

host

Given a processor handle processor_handle, this function will write current xgmi plpd settings to policy. All the processors at the same socket will have the same policy.

Parameters:

  • processor_handle – [in] a processor handle

  • xgmi_plpd – [inout] the xgmi plpd for this processor. 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_status_t amdsmi_set_xgmi_plpd(amdsmi_processor_handle processor_handle, uint32_t policy_id)#

Set the xgmi per-link power down policy parameter for the processor.

Platform:

gpu_bm_linux

guest_1vf

host

Given a processor handle processor_handle and a dpm policy policy_id, this function will set the xgmi plpd for this processor. All the processors at the same socket will be set to the same policy.

Note

This function requires admin/sudo privileges

Parameters:
Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_process_isolation(amdsmi_processor_handle processor_handle, uint32_t *pisolate)#

Get the status of the Process Isolation.

Platform:

gpu_bm_linux

guest_1vf

guest_windows

Given a processor handle processor_handle, this function will write current process isolation status to pisolate. The 0 is the process isolation disabled, and the 1 is the process isolation enabled.

Parameters:

  • processor_handle – [in] a processor handle

  • pisolate – [inout] the process isolation status. 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_status_t amdsmi_set_gpu_process_isolation(amdsmi_processor_handle processor_handle, uint32_t pisolate)#

Enable/disable the system Process Isolation.

Platform:

gpu_bm_linux

guest_1vf

guest_windows

Given a processor handle processor_handle and a process isolation pisolate, flag, this function will set the Process Isolation for this processor. The 0 is the process isolation disabled, and the 1 is the process isolation enabled.

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

  • pisolate – [in] the process isolation status to set.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_clean_gpu_local_data(amdsmi_processor_handle processor_handle)#

Run the cleaner shader to clean up data in LDS/GPRs.

Platform:

gpu_bm_linux

guest_1vf

guest_windows

Given a processor handle processor_handle, this function will clean the local data of this processor. This can be called between user logins to prevent information leak.

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Fabric (The Fabric used for scale up networking)#

enum amdsmi_fabric_telemetry_category_t#

Fabric telemetry categories.

Values:

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_UNKNOWN#

Unknown telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_UALOE#

UALOE telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_SWITCH#

Switch telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_CRYPTO#

Crypto telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_PFC#

PFC telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_NETPORT#

Network Port telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_DERIVED_UALOE#

Derived UALOE telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_DERIVED_NETPORT#

Derived Network Port telemetry.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MAX#

Maximum number of categories.

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_INVALID#

Unknown telemetry.

enum amdsmi_fabric_telemetry_category_mask_t#

Fabric telemetry category bitmask values.

Values:

enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_UALOE#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_SWITCH#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_CRYPTO#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_PFC#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_NETPORT#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_DERIVED_UALOE#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_DERIVED_NETPORT#
enumerator AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK_ALL_KNOWN#

All known categories.

enum amdsmi_fabric_size_constants_t#

Fabric size constants.

Values:

enumerator AMDSMI_FABRIC_ACTIVE_ACCELERATORS_BITMAP_SIZE#

Active accelerators bitmap size (32 x 32-bit words = 1024 bits).

enumerator AMDSMI_FABRIC_MAX_LOCAL_GPUS#

Maximum local GPUs in fabric.

enum amdsmi_fabric_type_t#

Fabric type.

Values:

enumerator AMDSMI_FABRIC_TYPE_UALOE#
enumerator AMDSMI_FABRIC_TYPE_UNKNOWN#
enum amdsmi_fabric_npa_address_mode_t#

Fabric NPA address mode.

Values:

enumerator AMDSMI_FABRIC_NPA_ADDRESS_MODE_SOURCE_ALIASING#
enumerator AMDSMI_FABRIC_NPA_ADDRESS_MODE_SOURCE_IDENTIFICATION#
enumerator AMDSMI_FABRIC_NPA_ADDRESS_MODE_UNKNOWN#
enum amdsmi_fabric_accelerator_vpod_state_t#

Fabric accelerator vPoD state.

Values:

enumerator AMDSMI_FABRIC_ACCELERATOR_VPOD_STATE_UNCONFIGURED#
enumerator AMDSMI_FABRIC_ACCELERATOR_VPOD_STATE_CONFIGURED#
enumerator AMDSMI_FABRIC_ACCELERATOR_VPOD_STATE_READY#
enumerator AMDSMI_FABRIC_ACCELERATOR_VPOD_STATE_ACTIVE#
enumerator AMDSMI_FABRIC_ACCELERATOR_VPOD_STATE_ERROR#
enumerator AMDSMI_FABRIC_ACCELERATOR_VPOD_STATE_UNKNOWN#
amdsmi_status_t amdsmi_alloc_fabric_telemetry(amdsmi_processor_handle processor_handle, uint32_t category_mask, amdsmi_fabric_telemetry_t **telemetry)#

Allocate storage for Fabric telemetry data.

Platform:

gpu_bm_linux

host

This function allocates storage for Fabric telemetry data for the specified categories. The allocated storage can be reused for multiple telemetry retrievals.

Parameters:

  • processor_handle – [in] - Handle for the target processor

  • category_mask – [in] - Bitmask of telemetry categories to allocate, constructed using AMDSMI_FABRIC_TELEMETRY_CATEGORY_MASK(cat)

  • telemetry – [out] - Pointer to allocated telemetry structure

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_fabric_telemetry_data(amdsmi_processor_handle processor_handle, amdsmi_fabric_telemetry_t *telemetry)#

Get Fabric telemetry data.

Platform:

gpu_bm_linux

host

This function retrieves the latest Fabric telemetry data snapshot into pre-allocated storage.

Parameters:

  • processor_handle – [in] - Handle for the target processor

  • telemetry – [inout] - Pre-allocated telemetry structure to populate

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

const char *amdsmi_fabric_telem_id_to_string(uint64_t telem_id)#

Get string name for a telemetry item ID.

Platform:

gpu_bm_linux

Given a telemetry item ID telem_id, this function returns a pointer to a string containing the human-readable name for the specified telemetry item. The returned string is statically allocated and should not be freed by the caller.

Parameters:

  • telem_id – [in] The telemetry item ID for which the name is requested

Returns:

const char* | Pointer to string containing the telemetry item name, or UNKNOWN if the category or telemetry ID is not recognized

amdsmi_status_t amdsmi_free_fabric_telemetry(amdsmi_processor_handle processor_handle, amdsmi_fabric_telemetry_t *telemetry)#

Free Fabric telemetry storage.

Platform:

gpu_bm_linux

host

This function frees the storage allocated for Fabric telemetry data.

Parameters:

  • processor_handle – [in] - Handle for the target processor

  • telemetry – [in] - Telemetry structure to free

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_fabric_info(amdsmi_processor_handle processor_handle, amdsmi_fabric_info_t *info)#

Get Fabric device information.

Platform:

gpu_bm_linux

host

Reads optional UALoE fabric attributes from sysfs (one file per field). Missing or unreadable files are skipped so the call can return partial data:

  • any field that was not updated from sysfs keeps its sentinel value (ie: numeric fields at their maximum representable value, and unknown enumeration values where documented for amdsmi_fabric_info_v1_t).

  • The device BDF in info is always filled when the call completes successfully or returns AMDSMI_STATUS_NO_DATA.

Note

This path reads sysfs only. It does not require UALoE netlink (::ualoe_open) to succeed; that handle is still needed for fabric telemetry APIs.

Parameters:

  • processor_handle – [in] - Handle for the target processor

  • info – [out] - Pointer to Fabric information structure to be populated. Must be allocated by the caller. Written on every return except errors such as AMDSMI_STATUS_INVAL.

Returns:

amdsmi_status_t

  • AMDSMI_STATUS_SUCCESS if at least one sysfs file yielded usable content.

  • AMDSMI_STATUS_NO_DATA if no sysfs file yielded usable lines (output still contains BDF and default/sentinel fabric fields).

  • Other codes (e.g. invalid processor handle) on failure.

AMDSMI_FABRIC_LABEL_MAX_LENGTH

Fabric textual label structure.

Labels must be null terminated Maximum length of the textual label (must be null terminated)

AMDSMI_FABRIC_PPOD_ID_SIZE

Physical PoD Identifier size in bytes (128-bit UUID).

struct amdsmi_fabric_telemetry_item_t#
#include <amdsmi.h>

Fabric telemetry item structure.

struct amdsmi_fabric_label_t#
struct amdsmi_fabric_telemetry_instance_t#
#include <amdsmi.h>

Fabric telemetry instance structure.

Collection of telemetry data items for an instance of a category of telemetry

struct amdsmi_fabric_telemetry_dataset_t#
#include <amdsmi.h>

Fabric telemetry dataset structure.

Contains all telemetry for one category

struct amdsmi_fabric_telemetry_t#
#include <amdsmi.h>

Fabric telemetry structure.

Top level structure defining telemetry data for Fabric. Contains datasets for each category of telemetry. A null pointer means no telemetry is available for that category.

struct amdsmi_fabric_info_v1_t#
#include <amdsmi.h>

Fabric device configuration information (version 1).

struct amdsmi_fabric_info_ver_t#
struct amdsmi_fabric_info_t#
#include <amdsmi.h>

Fabric device information structure.

Version Queries#

amdsmi_status_t amdsmi_get_lib_version(amdsmi_version_t *version)#

Get the build version information for the currently running build of AMDSMI.

Platform:

gpu_bm_linux

cpu_bm

guest_1vf

guest_mvf

guest_windows

Get the major, minor, patch and build string for AMDSMI build currently in use through version

Parameters:

  • version – [inout] A pointer to an amdsmi_version_t structure that will be updated with the version information upon return.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

ECC Information#

amdsmi_status_t amdsmi_get_gpu_ecc_count(amdsmi_processor_handle processor_handle, amdsmi_gpu_block_t block, amdsmi_error_count_t *ec)#

Retrieve the error counts for a GPU block. It is not supported on virtual machine guest.

See RAS Error Count sysfs Interface (AMDGPU RAS Support - Linux Kernel documentation) to learn how these error counts are accessed.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle, an amdsmi_gpu_block_t block and a pointer to an amdsmi_error_count_t ec, this function will write the error count values for the GPU block indicated by block to memory pointed to by ec.

Parameters:

  • processor_handle – [in] a processor handle

  • block – [in] The block for which error counts should be retrieved

  • ec – [inout] A pointer to an amdsmi_error_count_t to which the error counts should be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_ecc_enabled(amdsmi_processor_handle processor_handle, uint64_t *enabled_blocks)#

Retrieve the enabled ECC bit-mask. It is not supported on virtual machine guest.

See RAS Error Count sysfs Interface (AMDGPU RAS Support - Linux Kernel documentation) to learn how these error counts are accessed.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle, and a pointer to a uint64_t enabled_mask, this function will write bits to memory pointed to by enabled_blocks. Upon a successful call, enabled_blocks can then be AND’d with elements of the amdsmi_gpu_block_t ennumeration to determine if the corresponding block has ECC enabled.

Note

Whether a block has ECC enabled or not in the device is independent of whether there is kernel support for error counting for that block. Although a block may be enabled, but there may not be kernel support for reading error counters for that block.

Parameters:

  • processor_handle – [in] a processor handle

  • enabled_blocks – [inout] A pointer to a uint64_t to which the enabled blocks bits will be written. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_total_ecc_count(amdsmi_processor_handle processor_handle, amdsmi_error_count_t *ec)#

Returns the total number of ECC errors (correctable, uncorrectable and deferred) in the given GPU. It is not supported on virtual machine guest.

See RAS Error Count sysfs Interface (AMDGPU RAS Support - Linux Kernel documentation) to learn how these error counts are accessed.

Platform:

gpu_bm_linux

host

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • ec – [out] Reference to ecc error count structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

RAS information#

amdsmi_status_t amdsmi_get_afids_from_cper(char *cper_buffer, uint32_t buf_size, uint64_t *afids, uint32_t *num_afids)#

Get the AFIDs from CPER buffer.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

A utility function which retrieves the AFIDs from the CPER record.

Parameters:

  • cper_buffer – [in] a pointer to the buffer with one CPER record. The caller must make sure the whole CPER record is loaded into the buffer.

  • buf_size – [in] is the size of the cper_buffer.

  • afids – [out] a pointer to an array of uint64_t to which the AF IDs will be written

  • num_afids – [inout] As input, the value passed through this parameter is the number of uint64_t that may be safely written to the memory pointed to by afids. This is the limit on how many AF IDs will be written to afids. On return, num_afids will contain the number of AF IDs written to afids, or the number of AF IDs that could have been written if enough memory had been provided. It is suggest to pass MAX_NUMBER_OF_AFIDS_PER_RECORD for all AF Ids.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_ras_feature_info(amdsmi_processor_handle processor_handle, amdsmi_ras_feature_t *ras_feature)#

Returns RAS features info.

Platform:

gpu_bm_linux

host

guest_windows

Parameters:

  • processor_handle – [in] Device handle which to query

  • ras_feature – [out] RAS features that are currently enabled and supported on the processor. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_cper_entries(amdsmi_processor_handle processor_handle, uint32_t severity_mask, char *cper_data, uint64_t *buf_size, amdsmi_cper_hdr_t **cper_hdrs, uint64_t *entry_count, uint64_t *cursor)#

Retrieve CPER entries cached in the driver.

The user will pass buffers to hold the CPER data and CPER headers. The library will fill the buffer based on the severity_mask user passed. It will also parse the CPER header and stored in the cper_hdrs array. The user can use the cper_hdrs to get the timestamp and other header information. A cursor is also returned to the user, which can be used to get the next set of CPER entries.

If there are more data than any of the buffers user pass, the library will return AMDSMI_STATUS_MORE_DATA. User can call the API again with the cursor returned at previous call to get more data. If the buffer size is too small to even hold one entry, the library will return AMDSMI_STATUS_OUT_OF_RESOURCES.

Even if the API returns AMDSMI_STATUS_MORE_DATA, the 2nd call may still get the entry_count == 0 as the driver cache may not contain the severity user is interested in. The API returns AMDSMI_STATUS_SUCCESS with entry_count == 0 and buf_size == 0 in this case so that user can ignore that call.

An empty CPER ring (no records) also returns AMDSMI_STATUS_SUCCESS with entry_count == 0 and buf_size == 0.

Platform:

gpu_bm_linux

host

guest_1vf

Parameters:

  • processor_handle – [in] Handle to the processor for which CPER entries are to be retrieved.

  • severity_mask – [in] The severity mask of the entries to be retrieved.

  • cper_data – [inout] Pointer to a buffer where the CPER data will be stored. User must allocate the buffer and set the buf_size correctly.

  • buf_size – [inout] Pointer to a variable that specifies the size of the cper_data. On return, it will contain the actual size of the data written to the cper_data.

  • cper_hdrs – [inout] Array of the parsed headers of the cper_data. The user must allocate the array of pointers to cper_hdr. The library will fill the array with the pointers to the parsed headers. The underlying data is in the cper_data buffer and only pointer is stored in this array.

  • entry_count – [inout] Pointer to a variable that specifies the array length of the cper_hdrs user allocated. On return, it will contain the actual entries written to the cper_hdrs.

  • cursor – [inout] Pointer to a variable that will contain the cursor for the next call.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Error Queries#

amdsmi_status_t amdsmi_get_gpu_ecc_status(amdsmi_processor_handle processor_handle, amdsmi_gpu_block_t block, amdsmi_ras_err_state_t *state)#

Retrieve the ECC status for a GPU block. It is not supported on virtual machine guest.

See RAS Error Count sysfs Interface (AMDGPU RAS Support - Linux Kernel documentation) to learn how these error counts are accessed.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, an amdsmi_gpu_block_t block and a pointer to an amdsmi_ras_err_state_t state, this function will write the current state for the GPU block indicated by block to memory pointed to by state.

Parameters:

  • processor_handle – [in] a processor handle

  • block – [in] The block for which error counts should be retrieved

  • state – [inout] A pointer to an amdsmi_ras_err_state_t to which the ECC state should be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_status_code_to_string(amdsmi_status_t status, const char **status_string)#

Get a description of a provided AMDSMI error status.

Platform:

gpu_bm_linux

host

cpu_bm

guest_1vf

guest_mvf

guest_windows

Set the provided pointer to a const char *, status_string, to a string containing a description of the provided error code status.

Parameters:

  • status – [in] The error status for which a description is desired

  • status_string – [inout] A pointer to a const char * which will be made to point to a description of the provided error code

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Performance Counter Functions#

amdsmi_status_t amdsmi_gpu_counter_group_supported(amdsmi_processor_handle processor_handle, amdsmi_event_group_t group)#

Tell if an event group is supported by a given device. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and an event group specifier group, tell if group type events are supported by the device associated with processor_handle

Parameters:

  • processor_handle – [in] processor handle of device being queried

  • group – [in] amdsmi_event_group_t identifier of group for which support is being queried

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_gpu_create_counter(amdsmi_processor_handle processor_handle, amdsmi_event_type_t type, amdsmi_event_handle_t *evnt_handle)#

Create a performance counter object.

Platform:

gpu_bm_linux

Create a performance counter object of type type for the device with a processor handle of processor_handle, and write a handle to the object to the memory location pointed to by evnt_handle. evnt_handle can be used with other performance event operations. The handle should be deallocated with amdsmi_gpu_destroy_counter() when no longer needed.

Note

This function requires admin/sudo privileges

Parameters:

  • processor_handle – [in] a processor handle

  • type – [in] the amdsmi_event_type_t of performance event to create

  • evnt_handle – [inout] A pointer to a amdsmi_event_handle_t which will be associated with a newly allocated counter If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_gpu_destroy_counter(amdsmi_event_handle_t evnt_handle)#

Deallocate a performance counter object.

Platform:

gpu_bm_linux

Deallocate the performance counter object with the provided amdsmi_event_handle_t evnt_handle

Note

This function requires admin/sudo privileges

Parameters:

  • evnt_handle – [in] handle to event object to be deallocated

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_gpu_control_counter(amdsmi_event_handle_t evt_handle, amdsmi_counter_command_t cmd, void *cmd_args)#

Issue performance counter control commands. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Issue a command cmd on the event counter associated with the provided handle evt_handle.

Note

This function requires admin/sudo privileges

Parameters:

  • evt_handle – [in] an event handle

  • cmd – [in] The event counter command to be issued

  • cmd_args – [inout] Currently not used. Should be set to NULL.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_gpu_read_counter(amdsmi_event_handle_t evt_handle, amdsmi_counter_value_t *value)#

Read the current value of a performance counter.

Platform:

gpu_bm_linux

Read the current counter value of the counter associated with the provided handle evt_handle and write the value to the location pointed to by value.

Note

This function requires admin/sudo privileges

Parameters:

  • evt_handle – [in] an event handle

  • value – [inout] pointer to memory of size of amdsmi_counter_value_t to which the counter value will be written

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_available_counters(amdsmi_processor_handle processor_handle, amdsmi_event_group_t grp, uint32_t *available)#

Get the number of currently available counters. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a performance event group grp, and a pointer to a uint32_t available, this function will write the number of grp type counters that are available on the device with handle processor_handle to the memory that available points to.

Parameters:

  • processor_handle – [in] a processor handle

  • grp – [in] an event device group

  • available – [inout] A pointer to a uint32_t to which the number of available counters will be written

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

System Information Functions#

amdsmi_status_t amdsmi_get_gpu_compute_process_info(amdsmi_process_info_t *procs, uint32_t *num_items)#

Get process information about processes currently using GPU.

Platform:

gpu_bm_linux

Given a non-NULL pointer to an array procs of amdsmi_process_info_t’s, of length *num_items, this function will write up to *num_items instances of amdsmi_process_info_t to the memory pointed to by procs. These instances contain information about each process utilizing a GPU. If procs is not NULL, num_items will be updated with the number of processes actually written. If procs is NULL, num_items will be updated with the number of processes for which there is current process information. Calling this function with procs being NULL is a way to determine how much memory should be allocated for when procs is not NULL.

Parameters:

  • procs – [inout] a pointer to memory provided by the caller to which process information will be written. This may be NULL in which case only num_items will be updated with the number of processes found.

  • num_items – [inout] A pointer to a uint32_t, which on input, should contain the amount of memory in amdsmi_process_info_t’s which have been provided by the procs argument. On output, if procs is non-NULL, this will be updated with the number amdsmi_process_info_t structs actually written. If procs is NULL, this argument will be updated with the number processes for which there is information.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_compute_process_info_by_pid(uint32_t pid, amdsmi_process_info_t *proc)#

Get process information about a specific process.

Platform:

gpu_bm_linux

Given a pointer to an amdsmi_process_info_t proc and a process id pid, this function will write the process information for pid, if available, to the memory pointed to by proc.

Parameters:

  • pid – [in] The process ID for which process information is being requested

  • proc – [inout] a pointer to a amdsmi_process_info_t to which process information for pid will be written if it is found.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_compute_process_gpus(uint32_t pid, uint32_t *dv_indices, uint32_t *num_devices)#

Get the device indices currently being used by a process.

Platform:

gpu_bm_linux

Given a process id pid, a non-NULL pointer to an array of uint32_t’s processor_handleices of length *num_devices, this function will write up to num_devices device indices to the memory pointed to by processor_handleices. If processor_handleices is not NULL, num_devices will be updated with the number of gpu’s currently being used by process pid. If processor_handleices is NULL, processor_handleices will be updated with the number of gpus currently being used by pid. Calling this function with dv_indices being NULL is a way to determine how much memory is required for when processor_handleices is not NULL.

Parameters:

  • pid – [in] The process id of the process for which the number of gpus currently being used is requested

  • dv_indices – [inout] a pointer to memory provided by the caller to which indices of devices currently being used by the process will be written. This may be NULL in which case only num_devices will be updated with the number of devices being used.

  • num_devices – [inout] A pointer to a uint32_t, which on input, should contain the amount of memory in uint32_t’s which have been provided by the processor_handleices argument. On output, if processor_handleices is non-NULL, this will be updated with the number uint32_t’s actually written. If processor_handleices is NULL, this argument will be updated with the number devices being used.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

XGMI Functions#

amdsmi_status_t amdsmi_gpu_xgmi_error_status(amdsmi_processor_handle processor_handle, amdsmi_xgmi_status_t *status)#

Retrieve the XGMI error status for a device. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, and a pointer to an amdsmi_xgmi_status_t status, this function will write the current XGMI error state amdsmi_xgmi_status_t for the device processor_handle to the memory pointed to by status.

Parameters:

  • processor_handle – [in] a processor handle

  • status – [inout] A pointer to an amdsmi_xgmi_status_t to which the XGMI error state should be written If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_reset_gpu_xgmi_error(amdsmi_processor_handle processor_handle)#

Reset the XGMI error status for a device. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, this function will reset the current XGMI error state amdsmi_xgmi_status_t for the device processor_handle to amdsmi_xgmi_status_t::AMDSMI_XGMI_STATUS_NO_ERRORS

Parameters:

  • processor_handle – [in] a processor handle

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_xgmi_info(amdsmi_processor_handle processor_handle, amdsmi_xgmi_info_t *info)#

Returns XGMI information for the GPU.

Platform:

gpu_bm_linux

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to xgmi information structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Get the XGMI link status.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, this function will return the link status for each XGMI link connect to this processor. If the processor link type is not XGMI, it should return AMDSMI_STATUS_NOT_SUPPORTED.

Parameters:

  • processor_handle – [in] a processor handle

  • link_status – [out] The link status of the XGMI connect to this processor.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Hardware Topology Functions#

Return link metric information.

Platform:

gpu_bm_linux

host

Parameters:

  • processor_handle – [in] PF of a processor for which to query

  • link_metrics – [out] reference to the link metrics struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_topo_get_numa_node_number(amdsmi_processor_handle processor_handle, uint32_t *numa_node)#

Retrieve the NUMA CPU node number for a device.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle, and a pointer to an uint32_t numa_node, this function will write the node number of NUMA CPU for the device processor_handle to the memory pointed to by numa_node.

Parameters:

  • processor_handle – [in] a processor handle

  • numa_node – [inout] A pointer to an uint32_t to which the numa node number should be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Retrieve the weight for a connection between 2 GPUs.

Platform:

gpu_bm_linux

Given a source processor handle processor_handle_src and a destination processor handle processor_handle_dst, and a pointer to an uint64_t weight, this function will write the weight for the connection between the device processor_handle_src and processor_handle_dst to the memory pointed to by weight.

The weight is a qualitative cost metric derived from the KFD io_link weight property (lower values indicate closer or faster connections), similar in spirit to the NUMA distances reported by numactl. The value is computed as follows:

  • Each physical xGMI hop contributes 15, so an xGMI route traversing N physical links has a weight of 15*N. A single-hop xGMI connection has a weight of 15.

  • PCIe segments are summed over all segments (GPU→CPU + CPU→CPU + CPU→GPU). Each GPU-to-CPU segment typically contributes 20. The CPU-to-CPU segment uses the actual io_link weight when available; if that weight cannot be read, a fallback value of 10 is used for that segment.

Parameters:

  • processor_handle_src – [in] the source processor handle

  • processor_handle_dst – [in] the destination processor handle

  • weight – [inout] A pointer to an uint64_t to which the weight for the connection should be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_minmax_bandwidth_between_processors(amdsmi_processor_handle processor_handle_src, amdsmi_processor_handle processor_handle_dst, uint64_t *min_bandwidth, uint64_t *max_bandwidth)#

Retrieve minimal and maximal io link bandwidth between 2 GPUs.

Platform:

gpu_bm_linux

Given a source processor handle processor_handle_src and a destination processor handle processor_handle_dst, pointer to an uint64_t min_bandwidth, and a pointer to uint64_t max_bandiwidth, this function will write theoretical minimal and maximal bandwidth limits. API works if src and dst are connected via xgmi and have 1 hop distance.

Parameters:

  • processor_handle_src – [in] the source processor handle

  • processor_handle_dst – [in] the destination processor handle

  • min_bandwidth – [inout] A pointer to an uint64_t to which the minimal bandwidth for the connection should be written.

  • max_bandwidth – [inout] A pointer to an uint64_t to which the maximal bandwidth for the connection should be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Retrieve the hops and the connection type between 2 GPUs.

Platform:

gpu_bm_linux

Given a source processor handle processor_handle_src and a destination processor handle processor_handle_dst, and a pointer to an uint64_t hops and a pointer to an amdsmi_link_type_t type, this function will write the number of hops and the connection type between the device processor_handle_src and processor_handle_dst to the memory pointed to by hops and type.

Value

Meaning

1

The two GPUs are reachable over xGMI, regardless of how many physical xGMI links the route traverses.

2

The two GPUs communicate over PCIe within the same CPU NUMA node.

3

The two GPUs communicate over PCIe across different CPU NUMA nodes.

4

Fallback value used when the inter-CPU io_link weight cannot be read.

Two GPUs on the same xGMI fabric always report a hop count of 1, even when the data physically crosses several xGMI links. To obtain the literal number of physical xGMI links between two devices, read the value exposed by the amdgpu driver at `/sys/class/drm/card{0,1,…}/device/xgmi_num_hops` instead.

Note

The value written to hops is an abstracted topology step count, not the number of physical xGMI links traversed. The possible values are:

Parameters:

  • processor_handle_src – [in] the source processor handle

  • processor_handle_dst – [in] the destination processor handle

  • hops – [inout] A pointer to an uint64_t to which the abstracted hop count for the connection should be written.

  • type – [inout] A pointer to an amdsmi_link_type_t to which the type for the connection should be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Retrieve the set of GPUs that are nearest to a given device at a specific interconnectivity level.

Platform:

gpu_bm_linux

host

Once called topology_nearest_info will get populated with a list of all nearest devices for a given link_type. The list has a count of the number of devices found and their respective handles/identifiers.

Parameters:

  • processor_handle – [in] The identifier of the given device.

  • link_type – [in] The amdsmi_link_type_t level to search for nearest GPUs.

  • topology_nearest_info – [inout] .count;

    • When zero, set to the number of matching GPUs such that .device_list can be malloc’d.

    • When non-zero, .device_list will be filled with count number of processor_handle. .device_list An array of processor_handle for GPUs found at level.

Returns:

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

amdsmi_status_t amdsmi_is_P2P_accessible(amdsmi_processor_handle processor_handle_src, amdsmi_processor_handle processor_handle_dst, bool *accessible)#

Return P2P availability status between 2 GPUs.

Platform:

gpu_bm_linux

Given a source processor handle processor_handle_src and a destination processor handle processor_handle_dst, and a pointer to a bool accessible, this function will write the P2P connection status between the device processor_handle_src and processor_handle_dst to the memory pointed to by accessible.

Parameters:

  • processor_handle_src – [in] the source processor handle

  • processor_handle_dst – [in] the destination processor handle

  • accessible – [inout] A pointer to a bool to which the status for the P2P connection availability should be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_topo_get_p2p_status(amdsmi_processor_handle processor_handle_src, amdsmi_processor_handle processor_handle_dst, amdsmi_link_type_t *type, amdsmi_p2p_capability_t *cap)#

Retrieve connection type and P2P capabilities between 2 GPUs.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

Given a source processor handle processor_handle_src and a destination processor handle processor_handle_dst, a pointer to an amdsmi_link_type_t type, and a pointer to amdsmi_p2p_capability_t cap. This function will write the connection type, and io link capabilities between the device processor_handle_src and processor_handle_dst to the memory pointed to by cap and type.

Parameters:

  • processor_handle_src – [in] the source processor handle

  • processor_handle_dst – [in] the destination processor handle

  • type – [inout] A pointer to an amdsmi_link_type_t to which the type for the connection should be written.

  • cap – [inout] A pointer to an amdsmi_p2p_capability_t to which the io link capabilities should be written.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Compute Partition Functions#

amdsmi_status_t amdsmi_get_gpu_compute_partition(amdsmi_processor_handle processor_handle, char *compute_partition, uint32_t len)#

Retrieves the current compute partitioning for a desired device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a string compute_partition , and uint32 len , this function will attempt to obtain the device’s current compute partition setting string. Upon successful retrieval, the obtained device’s compute partition settings string shall be stored in the passed compute_partition char string variable.

Parameters:

  • processor_handle – [in] Device which to query

  • compute_partition – [inout] a pointer to a char string variable, which the device’s current compute partition will be written to.

  • len – [in] the length of the caller provided buffer compute_partition, suggested length is 4 or greater.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

  • AMDSMI_STATUS_UNEXPECTED_DATA – data provided to function is not valid

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function

  • AMDSMI_STATUS_INSUFFICIENT_SIZE – is returned if len bytes is not large enough to hold the entire compute partition value. In this case, only len bytes will be written.

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_set_gpu_compute_partition(amdsmi_processor_handle processor_handle, amdsmi_compute_partition_type_t compute_partition)#

Modifies a selected device’s compute partition setting.

Platform:

gpu_bm_linux

Given a processor handle processor_handle, a type of compute partition compute_partition, this function will attempt to update the selected device’s compute partition setting. This function does not allow any concurrent operations. Device must be idle and have no workloads when performing set partition operations.

Parameters:

  • processor_handle – [in] Device which to query

  • compute_partition – [in] using enum amdsmi_compute_partition_type_t, define what the selected device’s compute partition setting should be updated to.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_NO_PERM – function requires admin/sudo privileges

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

  • AMDSMI_STATUS_SETTING_UNAVAILABLE – the provided setting is unavailable for current device

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_get_gpu_compute_partition_mem_alloc_mode(amdsmi_processor_handle processor_handle, amdsmi_compute_partition_mem_alloc_mode_t *mode)#

Retrieves the current compute partition memory allocation mode for a desired device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a pointer mode, this function will attempt to obtain the device’s current compute partition memory allocation mode. The mode controls how HBM capacity is distributed across XCPs within each memory partition:

Parameters:

  • processor_handle – [in] Device which to query

  • mode – [out] a pointer to an amdsmi_compute_partition_mem_alloc_mode_t variable, into which the device’s current memory allocation mode will be written.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

  • AMDSMI_STATUS_UNEXPECTED_DATA – data provided to function is not valid

  • AMDSMI_STATUS_FILE_ERROR – problem accessing the sysfs file

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function

amdsmi_status_t amdsmi_set_gpu_compute_partition_mem_alloc_mode(amdsmi_processor_handle processor_handle, amdsmi_compute_partition_mem_alloc_mode_t mode)#

Modifies a selected device’s compute partition memory allocation mode.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a mode mode, this function will attempt to update the selected device’s compute partition memory allocation mode. The mode controls how HBM capacity is distributed across XCPs within each memory partition:

Parameters:
Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_NO_PERM – function requires admin/sudo privileges

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

  • AMDSMI_STATUS_FILE_ERROR – problem accessing the sysfs file

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function

Memory Partition Functions#

amdsmi_status_t amdsmi_get_gpu_memory_partition(amdsmi_processor_handle processor_handle, char *memory_partition, uint32_t len)#

Retrieves the current memory partition for a desired device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a string memory_partition , and uint32 len , this function will attempt to obtain the device’s memory partition string. Upon successful retrieval, the obtained device’s memory partition string shall be stored in the passed memory_partition char string variable.

Parameters:

  • processor_handle – [in] Device which to query

  • memory_partition – [inout] a pointer to a char string variable, which the device’s memory partition will be written to.

  • len – [in] the length of the caller provided buffer memory_partition , suggested length is 5 or greater.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

  • AMDSMI_STATUS_UNEXPECTED_DATA – data provided to function is not valid

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function

  • AMDSMI_STATUS_INSUFFICIENT_SIZE – is returned if len bytes is not large enough to hold the entire memory partition value. In this case, only len bytes will be written.

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_set_gpu_memory_partition(amdsmi_processor_handle processor_handle, amdsmi_memory_partition_type_t memory_partition)#

Modifies a selected device’s current memory partition setting.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a type of memory partition memory_partition, this function will attempt to update the selected device’s memory partition setting. This function does not allow any concurrent operations. Device must be idle and have no workloads when performing set partition operations.

On

Platform:

gpu_bm_linux AMDGPU driver restart is REQUIRED to complete updating to the new memory partition setting. Refer to amdsmi_gpu_driver_reload() for more details.

Parameters:

  • processor_handle – [in] Device which to query

  • memory_partition – [in] using enum amdsmi_memory_partition_type_t, define what the selected device’s current mode setting should be updated to.

Return values:

  • AMDSMI_STATUS_SUCCESS – call was successful

  • AMDSMI_STATUS_NO_PERM – function requires admin/sudo privileges

  • AMDSMI_STATUS_INVAL – the provided arguments are not valid

  • AMDSMI_STATUS_NOT_SUPPORTED – installed software or hardware does not support this function

  • AMDSMI_STATUS_BUSY – device is busy, a resource or mutex could not be acquired

Returns:

amdsmi_status_t

amdsmi_status_t amdsmi_get_gpu_memory_partition_config(amdsmi_processor_handle processor_handle, amdsmi_memory_partition_config_t *config)#

Returns current gpu memory partition capabilities.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

Parameters:

  • processor_handle – [in] a processor handle

  • config – [out] reference to the memory partition config. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_memory_partition_mode(amdsmi_processor_handle processor_handle, amdsmi_memory_partition_type_t mode)#

Sets memory partition mode Set memory partition setting based on memory_partition mode from amdsmi_get_gpu_memory_partition_config.

Platform:

gpu_bm_linux

host

Given a processor handle processor_handle and a type of memory partition mode, this function will attempt to update the selected device’s memory partition setting. This function does not allow any concurrent operations. Device must be idle and have no workloads when performing set partition operations.

On

Platform:

gpu_bm_linux AMDGPU driver restart is REQUIRED to complete updating to the new memory partition setting. Refer to amdsmi_gpu_driver_reload() for more details.

On

Platform:

gpu_bm_linux AMDGPU driver restart is REQUIRED to complete updating to the new memory partition setting. Refer to amdsmi_gpu_driver_reload() for more details.

Parameters:

  • processor_handle – [in] A processor handle

  • mode – [in] Enum representing memory partitioning mode to set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Accelerator Partition Profile Functions#

amdsmi_status_t amdsmi_get_gpu_accelerator_partition_profile_config(amdsmi_processor_handle processor_handle, amdsmi_accelerator_partition_profile_config_t *profile_config)#

Returns gpu accelerator partition caps as currently configured in the system.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

Platform:

gpu_bm_linux or any resources for

host.

Note

API requires admin/sudo privileges or API will not be able to read all resources for

Parameters:

  • processor_handle – [in] Device which to query

  • profile_config – [out] reference to the accelerator partition config. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_accelerator_partition_profile(amdsmi_processor_handle processor_handle, amdsmi_accelerator_partition_profile_t *profile, uint32_t *partition_id)#

Returns current gpu accelerator partition cap.

Platform:

gpu_bm_linux or any resources for

host.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

Note

API requires admin/sudo privileges or API will not be able to read all resources for

Parameters:

  • processor_handle – [in] Device which to query

  • profile – [out] reference to the accelerator partition profile. Must be allocated by user.

  • partition_id – [inout] array of ids for current accelerator profile. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_accelerator_partition_profile(amdsmi_processor_handle processor_handle, uint32_t profile_index)#

Set accelerator partition setting based on profile_index from amdsmi_get_gpu_accelerator_partition_profile_config.

Platform:

gpu_bm_linux

host

Platform:

gpu_bm_linux or any resources for

host.

Note

API requires admin/sudo privileges or API will not be able to read all resources for

Parameters:

  • processor_handle – [in] Device which to query

  • profile_index – [in] Represents index of a partition user wants to set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Event Notification Functions#

amdsmi_status_t amdsmi_init_gpu_event_notification(amdsmi_processor_handle processor_handle)#

Prepare to collect event notifications for a GPU.

Platform:

gpu_bm_linux

This function prepares to collect events for the GPU with device ID processor_handle, by initializing any required system parameters. This call may open files which will remain open until amdsmi_stop_gpu_event_notification() is called.

Parameters:

  • processor_handle – [in] a processor handle corresponding to the device on which to listen for events

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_gpu_event_notification_mask(amdsmi_processor_handle processor_handle, uint64_t mask)#

Specify which events to collect for a device.

Platform:

gpu_bm_linux

Given a processor handle processor_handle and a mask consisting of elements of amdsmi_evt_notification_type_t OR’d together, this function will listen for the events specified in mask on the device corresponding to processor_handle.

Note

AMDSMI_STATUS_INIT_ERROR is returned if amdsmi_init_gpu_event_notification() has not been called before a call to this function

Parameters:

  • processor_handle – [in] a processor handle corresponding to the device on which to listen for events

  • mask – [in] Bitmask generated by OR’ing 1 or more elements of amdsmi_evt_notification_type_t indicating which event types to listen for, where the amdsmi_evt_notification_type_t value indicates the bit field, with bit position starting from 1. For example, if the mask field is 0x0000000000000003, which means first bit, bit 1 (bit position start from 1) and bit 2 are set, which indicate interest in receiving AMDSMI_EVT_NOTIF_VMFAULT (which has a value of 1) and AMDSMI_EVT_NOTIF_THERMAL_THROTTLE event (which has a value of 2).

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_event_notification(int timeout_ms, uint32_t *num_elem, amdsmi_evt_notification_data_t *data)#

Collect event notifications, waiting a specified amount of time.

Platform:

gpu_bm_linux

Given a time period timeout_ms in milliseconds and a caller- provided buffer of amdsmi_evt_notification_data_t’s data with a length (in amdsmi_evt_notification_data_t’s, also specified by the caller) in the memory location pointed to by num_elem, this function will collect amdsmi_evt_notification_type_t events for up to timeout_ms milliseconds, and write up to *num_elem event items to data. Upon return num_elem is updated with the number of events that were actually written. If events are already present when this function is called, it will write the events to the buffer then poll for new events if there is still caller-provided buffer available to write any new events that would be found.

This function requires prior calls to amdsmi_init_gpu_event_notification() and :: amdsmi_set_gpu_event_notification_mask(). This function polls for the occurrence of the events on the respective devices that were previously specified by :: amdsmi_set_gpu_event_notification_mask().

Parameters:

  • timeout_ms – [in] number of milliseconds to wait for an event to occur

  • num_elem – [inout] pointer to uint32_t, provided by the caller. On input, this value tells how many amdsmi_evt_notification_data_t elements are being provided by the caller with data. On output, the location pointed to by num_elem will contain the number of items written to the provided buffer.

  • data – [out] pointer to a caller-provided memory buffer of size num_elem amdsmi_evt_notification_data_t to which this function may safely write. If there are events found, up to num_elem event items will be written to data.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_stop_gpu_event_notification(amdsmi_processor_handle processor_handle)#

Close any file handles and free any resources used by event notification for a GPU.

Platform:

gpu_bm_linux

Any resources used by event notification for the GPU with processor handle processor_handle will be free with this function. This includes freeing any memory and closing file handles. This should be called for every call to amdsmi_init_gpu_event_notification()

Parameters:

  • processor_handle – [in] The processor handle of the GPU for which event notification resources will be free

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Software Version Information#

amdsmi_status_t amdsmi_get_gpu_driver_info(amdsmi_processor_handle processor_handle, amdsmi_driver_info_t *info)#

Returns the driver version information.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to driver information structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

ASIC & Board Static Information#

amdsmi_status_t amdsmi_get_gpu_asic_info(amdsmi_processor_handle processor_handle, amdsmi_asic_info_t *info)#

Returns the ASIC information for the device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

This function returns ASIC information such as the product name, the vendor ID, the subvendor ID, the device ID, the revision ID and the serial number.

Note

The processor_handle that contains amdsmi_asic_info_t member oam_id = 0 corresponds to the socket that contains baseboard information.

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to static asic information structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_kfd_info(amdsmi_processor_handle processor_handle, amdsmi_kfd_info_t *info)#

Returns the KFD (Kernel Fusion Driver) information for the device.

Platform:

gpu_bm_linux

This function returns KFD information populated into the amdsmi_kfd_info_t. This contains the kfd_id and node_id which allow for the ID and index of this device in the KFD.

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to kfd information structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_vram_info(amdsmi_processor_handle processor_handle, amdsmi_vram_info_t *info)#

Returns vram info.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

Parameters:

  • processor_handle – [in] PF of a processor for which to query

  • info – [out] Reference to vram info structure Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_board_info(amdsmi_processor_handle processor_handle, amdsmi_board_info_t *info)#

Returns the board part number and board information for the requested device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to board info structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_power_cap_info(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, amdsmi_power_cap_info_t *info)#

Returns the power caps as currently configured in the system.

Platform:

gpu_bm_linux

host

guest_windows

Platform:

host.

Parameters:

  • processor_handle – [in] Device which to query

  • sensor_ind – [in] A 0-based sensor index. Normally, this will be 0. If a device has more than one sensor, it could be greater than 0. Parameter sensor_ind is unused on

  • info – [out] Reference to power caps information structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_pcie_info(amdsmi_processor_handle processor_handle, amdsmi_pcie_info_t *info)#

Returns the PCIe info for the GPU.

Platform:

gpu_bm_linux

host

guest_1vf

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to the PCIe information returned by the library. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_xcd_counter(amdsmi_processor_handle processor_handle, uint16_t *xcd_count)#

Returns the ‘xcd_counter’ from the GPU metrics associated with the device.

Platform:

gpu_bm_linux

guest_1vf

guest_mvf

Parameters:

  • processor_handle – [in] Device which to query

  • xcd_count – [inout] a pointer to uint16_t to which the device gpu metric unit will be stored. Must be allocated by user.

Return values:

AMDSMI_STATUS_SUCCESS – is returned upon successful call. AMDSMI_STATUS_NOT_SUPPORTED is returned in case the metric unit does not exist for the given device.

Node Information#

amdsmi_status_t amdsmi_get_npm_info(amdsmi_node_handle node_handle, amdsmi_npm_info_t *info)#

Retrieves node power management (NPM) status and power limit for the specified node.

Platform:

gpu_bm_linux

host

This function queries the NPM controller for the given node and returns whether NPM is enabled, along with the current node-level power limit in Watts. The NPM status and limit are set out-of-band and reported via this API.

Parameters:

  • node_handle – [in] Handle to the Node to query.

  • info – [out] Pointer to amdsmi_npm_info_t structure to receive NPM status and limit. Must be allocated by the user.

Returns:

AMDSMI_STATUS_SUCCESS on success, non-zero on failure.

Firmware & VBIOS queries#

amdsmi_status_t amdsmi_get_fw_info(amdsmi_processor_handle processor_handle, amdsmi_fw_info_t *info)#

Returns the firmware versions running on the device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to the fw info. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_vbios_info(amdsmi_processor_handle processor_handle, amdsmi_vbios_info_t *info)#

Returns the static information for the vBIOS on the device.

Platform:

gpu_bm_linux

host

guest_1vf

guest_mvf

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to static vBIOS information. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

GPU Monitoring#

amdsmi_status_t amdsmi_get_temp_metric(amdsmi_processor_handle processor_handle, amdsmi_temperature_type_t sensor_type, amdsmi_temperature_metric_t metric, int64_t *temperature)#

Get the temperature metric value for the specified metric, from the specified temperature sensor on the specified device. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

host

guest_windows

Given a processor handle processor_handle, a sensor type sensor_type, a amdsmi_temperature_metric_t metric and a pointer to an int64_t temperature, this function will write the value of the metric indicated by metric and sensor_type to the memory location temperature.

Parameters:

  • processor_handle – [in] a processor handle

  • sensor_type – [in] part of device from which temperature should be obtained. This should come from the enum amdsmi_temperature_type_t

  • metric – [in] enum indicated which temperature value should be retrieved

  • temperature – [inout] a pointer to int64_t to which the temperature is in Celsius. If this parameter is nullptr, this function will return AMDSMI_STATUS_INVAL if the function is supported with the provided, arguments and AMDSMI_STATUS_NOT_SUPPORTED if it is not supported with the provided arguments.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_activity(amdsmi_processor_handle processor_handle, amdsmi_engine_usage_t *info)#

Returns the current usage of the GPU engines (GFX, MM and MEM). Each usage is reported as a percentage from 0-100%.

Platform:

gpu_bm_linux

host

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to the gpu engine usage structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_power_info(amdsmi_processor_handle processor_handle, amdsmi_power_info_t *info)#

Returns the current power and voltage of the GPU.

Platform:

gpu_bm_linux

host

guest_windows

Note

amdsmi_power_info_t::socket_power metric can rarely spike above the socket power limit in some cases

Note

unsupported struct members are set to UINT32_MAX

Parameters:

  • processor_handle – [in] PF of a processor for which to query

  • info – [out] Reference to the gpu power structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_is_gpu_power_management_enabled(amdsmi_processor_handle processor_handle, bool *enabled)#

Returns is power management enabled.

Platform:

gpu_bm_linux

host

Parameters:

  • processor_handle – [in] PF of a processor for which to query

  • enabled – [out] Reference to bool. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_clock_info(amdsmi_processor_handle processor_handle, amdsmi_clk_type_t clk_type, amdsmi_clk_info_t *info)#

Returns the measurements of the clocks in the GPU for the GFX and multimedia engines and Memory. This call reports the averages over 1s in MHz. It is not supported on virtual machine guest.

Platform:

gpu_bm_linux

host

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • clk_type – [in] Enum representing the clock type to query.

  • info – [out] Reference to the gpu clock structure. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_vram_usage(amdsmi_processor_handle processor_handle, amdsmi_vram_usage_t *info)#

Returns the VRAM usage (both total and used memory) in MegaBytes.

Platform:

gpu_bm_linux

guest_windows

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to vram information. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_violation_status(amdsmi_processor_handle processor_handle, amdsmi_violation_status_t *info)#

Returns the violations for a processor.

Warning: API will be slow due to polling driver for 2 samples. Require a minimum wait of 100ms between the 2 samples in order to calculate. Otherwise users would need to use amdsmi_get_gpu_metrics_info for BM. See that API’s struct for calculations.

Platform:

gpu_bm_linux

Parameters:

  • processor_handle – [in] Device which to query

  • info – [out] Reference to all violation status details available. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Process information#

amdsmi_status_t amdsmi_get_gpu_process_list(amdsmi_processor_handle processor_handle, uint32_t *max_processes, amdsmi_proc_info_t *list)#

Returns the list of process information running on a given GPU. If pdh.dll is not present on the system, this API returns AMDSMI_STATUS_NOT_SUPPORTED. Sum of the process memory is not expected to be the total memory usage.

Platform:

gpu_bm_linux

guest_windows

For cases where max_process is not zero (0), it specifies the list’s size limit. That is, the maximum size this list will be able to hold. After the list is built internally, as a return status, we will have AMDSMI_STATUS_OUT_OF_RESOURCES when the original size limit is smaller than the actual list of processes running. Hence, the caller is aware the list size needs to be resized, or AMDSMI_STATUS_SUCCESS otherwise. Holding a copy of max_process before it is passed in will be helpful for monitoring the allocations done upon each call since the max_process will permanently be changed to reflect the actual number of processes running.

Note

The user provides a buffer to store the list and the maximum number of processes that can be returned. If the user sets max_processes to 0, the current total number of processes will replace max_processes param. After that, the function needs to be called again, with updated max_processes, to successfully fill the process list, which was previously allocated with max_processes

Note

If the reserved size for processes is smaller than the number of actual processes running. The AMDSMI_STATUS_OUT_OF_RESOURCES is an indication the caller should handle the situation (resize). The max_processes is always changed to reflect the actual size of list of processes running, so the caller knows where it is at.

Warning

IMPORTANT: To get valid return values, at least 1 second needs to pass from starting the program to the first call of this function, and before every following call of this function after that, to get correct values

Parameters:

  • processor_handle – [in] Device which to query

  • max_processes – [inout] Reference to the size of the list buffer in number of elements. Returns the return number of elements in list or the number of running processes if equal to 0, and if given value in param max_processes is less than number of processes currently running, AMDSMI_STATUS_OUT_OF_RESOURCES will be returned.

  • list – [out] Reference to a user-provided buffer where the process list will be returned. This buffer must contain at least max_processes entries of type amd_proc_info_list_t. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, | AMDSMI_STATUS_OUT_OF_RESOURCES, filled list buffer with data, but number of actual running processes is larger than the size provided.

amdsmi_status_t amdsmi_get_gpu_process_list_by_pid(amdsmi_processor_handle *processor_handles, uint32_t num_processors, amdsmi_proc_info_by_pid_t *procs, uint32_t *max_processes)#

Get the list of processes running on one or more GPUs, grouped by PID.

Aggregates per-GPU process lists across all provided processor handles and returns one entry per unique PID. Each entry contains the per-GPU breakdown for every GPU that PID is active on. Results are sorted ascending by PID.

Platform:

gpu_bm_linux

Parameters:

  • processor_handles – [in] Array of processor handles to query

  • num_processors – [in] Number of handles in processor_handles

  • procs – [out] Caller-allocated buffer of amdsmi_proc_info_by_pid_t. Pass NULL to query the required size via max_processes.

  • max_processes – [inout] On input: capacity of procs. On output: number of unique PIDs written (or required if procs is NULL).

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, | AMDSMI_STATUS_OUT_OF_RESOURCES if max_processes was too small, | AMDSMI_STATUS_INVAL if processor_handles is NULL or num_processors is 0

Driver control mechanisms#

amdsmi_status_t amdsmi_gpu_driver_reload(void)#

Restart the device driver (kmod module) for all AMD GPUs on the system.

Platform:

gpu_bm_linux

guest_1vf

guest_mvf

This function will reload the AMD GPU driver as described in the Linux kernel documentation - https://docs.kernel.org/admin-guide/sysctl/kernel.html#modprobe with no extra parameters as specified in https://docs.kernel.org/gpu/amdgpu/module-parameters.html.

Use this function with caution, as it will unload and reload the AMD GPU driver: modprobe -r amdgpu && modprobe amdgpu.

Any process or workload using the AMD GPU driver is REQUIRED to be stopped before calling this function. Otherwise, function will return AMDSMI_STATUS_AMDGPU_RESTART_ERR could not successfully restart the amdgpu driver.

User is REQUIRED to have root/admin privileges to call this function. Otherwise, this function will return AMDSMI_STATUS_NO_PERM.

This API will take time to complete, as we are checking the driver’s loading status to confirm it reloaded properly. If AMDSMI_STATUS_AMDGPU_RESTART_ERR is returned, it means the driver did not reload properly and the user should check dmesg logs.

This function has been created in order to conveniently reload the AMD GPU driver once amdsmi_set_gpu_memory_partition() or amdsmi_set_gpu_memory_partition_mode() successfully has been changed on Baremetal systems. Now users can control the reload once all GPU processes/workloads have been stopped on the AMD GPU driver. A (AMD GPU) driver reload is REQUIRED to complete changing to the new memory partition configuration (amdsmi_set_gpu_memory_partition()/amdsmi_set_gpu_memory_partition_mode()) operation MUST be successful. This function WILL EFFECT all GPUs in the hive to be reconfigured with the specified memory partition configuration.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success

Returns:

| AMDSMI_STATUS_NO_PERM function requires admin/sudo privileges

Returns:

| AMDSMI_STATUS_AMDGPU_RESTART_ERR could not successfully restart the amdgpu driver.

Peak Tops Limiter#

amdsmi_status_t amdsmi_get_gpu_ptl_state(amdsmi_processor_handle processor_handle, bool *enabled)#

Get PTL enable/disable state.

Platform:

gpu_bm_linux

host

This function retrieves whether PTL (Peak Tops Limiter) is currently enabled or disabled for the specified processor. This is a simple state query that returns the current PTL operational state without detailed configuration.

Parameters:

  • processor_handle – [in] Device which to query

  • enabled – [out] Pointer to boolean that will be set to true if PTL is enabled, false if PTL is disabled

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, AMDSMI_STATUS_NOT_SUPPORTED if PTL is not supported on this device, non-zero on other failures

amdsmi_status_t amdsmi_set_gpu_ptl_state(amdsmi_processor_handle processor_handle, bool enable)#

Set PTL enable/disable state.

Platform:

gpu_bm_linux

host

This function enables or disables PTL (Peak Tops Limiter) operation. Use amdsmi_set_gpu_ptl_enable_with_formats() for more control over the preferred data formats when enabling.

Parameters:

  • processor_handle – [in] Device to configure

  • enable – [in] Boolean flag: true to enable PTL with default formats, false to disable PTL

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_gpu_ptl_formats(amdsmi_processor_handle processor_handle, amdsmi_ptl_data_format_t *data_format1, amdsmi_ptl_data_format_t *data_format2)#

Get PTL (Peak Tops Limiter) formats for the processor.

Platform:

gpu_bm_linux

host

This function retrieves the current PTL formats for the specified processor. PTL prevents the product to never deliver more than a specified TOPS/second. If function returns 0 for both formats, PTL was never enabled before on that system

Parameters:

  • processor_handle – [in] Device which to query

  • data_format1 – [out] Pointer to first preferred data format that receives peak performance

  • data_format2 – [out] Pointer to second preferred data format that receives peak performance

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, AMDSMI_STATUS_NOT_SUPPORTED if PTL is not supported on this device, non-zero on other failures

amdsmi_status_t amdsmi_set_gpu_ptl_formats(amdsmi_processor_handle processor_handle, amdsmi_ptl_data_format_t data_format1, amdsmi_ptl_data_format_t data_format2)#

Set PTL with specified preferred data formats.

Platform:

gpu_bm_linux

host

This function sets PTL with the specified preferred data format pair. PTL must be enabled first before calling this function using amdsmi_set_gpu_ptl_state. The two specified formats will receive accurate performance monitoring and peak performance. F8 and XF32 formats always receive peak performance regardless of this setting.

Parameters:

  • processor_handle – [in] Device to configure

  • data_format1 – [in] First preferred data format (must be from the limited set: I8, F16, BF16, F32, F64)

  • data_format2 – [in] Second preferred data format (must be from the limited set: I8, F16, BF16, F32, F64, and different from data_format1)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, AMDSMI_STATUS_NOT_SUPPORTED if PTL is not supported on this device, non-zero on other failures

Discovery Queries#

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:

  • cpu_count – [inout] 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.

  • processor_handles – [inout] 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_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:

  • cores_count – [inout] 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.

  • processor_handles – [inout] 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

Energy information (RAPL MSR)#

amdsmi_status_t amdsmi_get_cpu_core_energy(amdsmi_processor_handle processor_handle, uint64_t *penergy)#

Get the core energy for a given core.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu core which to query

  • penergy – [inout] - Input buffer to return the core energy

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_energy(amdsmi_processor_handle processor_handle, uint64_t *penergy)#

Get the socket energy for a given socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • penergy – [inout] - Input buffer to return the socket energy

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

HSMP system statistics#

amdsmi_status_t amdsmi_get_threads_per_core(uint32_t *threads_per_core)#

Get Number of threads Per Core.

Platform:

cpu_bm

Parameters:

  • threads_per_core – [inout] - Input buffer to return the Number of threads Per Core

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_hsmp_driver_version(amdsmi_processor_handle processor_handle, amdsmi_hsmp_driver_version_t *amdsmi_hsmp_driver_ver)#

Get HSMP Driver Version.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • amdsmi_hsmp_driver_ver – [inout] - Input buffer to return the HSMP Driver version

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_smu_fw_version(amdsmi_processor_handle processor_handle, amdsmi_smu_fw_version_t *amdsmi_smu_fw)#

Get SMU Firmware Version.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • amdsmi_smu_fw – [inout] - Input buffer to return the firmware version

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_hsmp_proto_ver(amdsmi_processor_handle processor_handle, uint32_t *proto_ver)#

Get HSMP protocol Version.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • proto_ver – [inout] - Input buffer to return the protocol version

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_prochot_status(amdsmi_processor_handle processor_handle, uint32_t *prochot)#

Get normalized status of the processor’s PROCHOT status.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • prochot – [inout] - Input buffer to return the procohot status.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_fclk_mclk(amdsmi_processor_handle processor_handle, uint32_t *fclk, uint32_t *mclk)#

Get Data fabric clock and Memory clock in MHz.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • fclk – [inout] - Input buffer to return fclk

  • mclk – [inout] - Input buffer to return mclk

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_cclk_limit(amdsmi_processor_handle processor_handle, uint32_t *cclk)#

Get core clock in MHz.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • cclk – [inout] - Input buffer to return core clock

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_current_active_freq_limit(amdsmi_processor_handle processor_handle, uint16_t *freq, char **src_type)#

Get current active frequency limit of the socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • freq – [inout] - Input buffer to return frequency value in MHz

  • src_type – [inout] - Input buffer to return frequency source name

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_freq_range(amdsmi_processor_handle processor_handle, uint16_t *fmax, uint16_t *fmin)#

Get socket frequency range.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • fmax – [inout] - Input buffer to return maximum frequency

  • fmin – [inout] - Input buffer to return minimum frequency

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_core_current_freq_limit(amdsmi_processor_handle processor_handle, uint32_t *freq)#

Get socket frequency limit of the core.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu core which to query

  • freq – [inout] - Input buffer to return frequency.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_rail_isofreq_policy(amdsmi_processor_handle processor_handle, bool *rail_isofreq_policy)#

Set CPU rail isolated frequency policy for independent core clock control per power rail.

This API configures the frequency policy for CPU power rails.

  • If a socket-wide limit (e.g., PPT) is setting the core clock frequency, this setting has no effect.

  • For other limiters specific to CPU power rails (e.g., TDC), this policy enables or disables independent core clocks per rail (VDDCR_CPU0 or VDDCR_CPU1).

Policy values:

  • 0: Disable independent control (all cores on both rails have the same frequency limit)

  • 1: Enable independent control (each rail has an independent frequency limit)

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • rail_isofreq_policy – [inout] - Input buffer to store policy value, indicating the CPU rail ISO frequency Policy setting:

    • 0: Disable independent control - each rail has its own independent frequency limit.

    • 1: Enable independent control - all cores on both rails share the same frequency limit.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_rail_isofreq_policy(amdsmi_processor_handle processor_handle, uint8_t *rail_isofreq_policy)#

Get CPU rail isolated frequency policy status for independent core clock control per power rail.

This API retrieves the current frequency policy configuration for CPU power rails.

  • If a socket-wide limit (e.g., PPT) is setting the core clock frequency, the effective policy may be overridden.

  • For other limiters specific to CPU power rails (e.g., TDC), this policy indicates whether independent core clocks per rail (VDDCR_CPU0 or VDDCR_CPU1) are enabled or disabled.

Policy values returned:

  • 0: Independent control disabled (all cores on both rails have the same frequency limit)

  • 1: Independent control enabled (each rail has an independent frequency limit)

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • rail_isofreq_policy – [inout] - Input buffer to receive the current cpu rail isolated frequency policy

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success, non-zero on failure

ESMI DFC Control#

amdsmi_status_t amdsmi_set_cpu_dfc_ctrl(amdsmi_processor_handle processor_handle, uint8_t *dfc_ctrl)#

Set the DFCState enabling control.

DFCState control values for setting:

  • 0: Disable DFC control

  • 1: Enable DFC control

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket handle to query

  • dfc_ctrl – [in] - Input buffer indicating whether to enable (1) or disable (0) DFCState control

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success, non-zero on failure

amdsmi_status_t amdsmi_get_cpu_dfc_ctrl(amdsmi_processor_handle processor_handle, uint8_t *dfc_ctrl)#

Get the current DFCState enabling control status.

Returned DFCState control values:

  • 0: DFC control is disabled

  • 1: DFC control is enabled

    Platform:

    cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket handle to query

  • dfc_ctrl – [inout] - Input buffer to receive the current DFCState control status

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success, non-zero on failure

Performance (Boost limit) Control#

amdsmi_status_t amdsmi_get_cpu_core_boostlimit(amdsmi_processor_handle processor_handle, uint32_t *pboostlimit)#

Get the core boost limit.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu core which to query

  • pboostlimit – [inout] - Input buffer to fill the boostlimit value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_c0_residency(amdsmi_processor_handle processor_handle, uint32_t *pc0_residency)#

Get the socket c0 residency.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • pc0_residency – [inout] - Input buffer to fill the c0 residency value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_core_boostlimit(amdsmi_processor_handle processor_handle, uint32_t boostlimit)#

Set the core boostlimit value.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu core which to query

  • boostlimit – [in] - boostlimit value to be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_socket_boostlimit(amdsmi_processor_handle processor_handle, uint32_t boostlimit)#

Set the socket boostlimit value.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • boostlimit – [in] - boostlimit value to be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_core_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t *floor_freq)#

Get the CPU core floor limit frequency.

This function retrieves the floor frequency limit for the specified CPU core.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU core which to query

  • floor_freq – [inout] - Input buffer to fill the floor limit frequency in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t *floor_freq)#

Get the CPU floor limit frequency.

This function retrieves the floor frequency limit for the specified CPU socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU socket which to query

  • floor_freq – [inout] - Input buffer to fill the floor limit frequency in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_core_eff_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t *eff_floor_freq)#

Get the CPU core effective floor limit frequency.

This function returns the effective floor frequency limit for the specified CPU core.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU core which to query

  • eff_floor_freq – [inout] - Input buffer to fill the effective floor limit frequency in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_eff_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t *eff_floor_freq)#

Get the CPU effective floor limit frequency.

This function returns the effective floor frequency limit for the specified CPU socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU socket which to query

  • eff_floor_freq – [inout] - Input buffer to fill the effective floor limit frequency in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_core_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t floor_freq)#

Set the CPU core floor limit frequency.

This function sets the floor frequency limit for the specified CPU core.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU core which to set

  • floor_freq – [in] - floor limit frequency value to be set in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t floor_freq)#

Set the CPU socket floor limit frequency.

This function sets the floor frequency limit for the specified CPU socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU socket which to set

  • floor_freq – [in] - floor limit frequency value to be set in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_msr_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t msr_floor_freq)#

Set CPU floor limit frequency via MSR(Model Specific Register).

This function sets the floor frequency limit via MSR(Model Specific Register) for the specified CPU socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU socket which to set

  • msr_floor_freq – [in] - MSR floor limit frequency value to be set in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_core_msr_floor_freq_limit(amdsmi_processor_handle processor_handle, uint32_t msr_floor_freq)#

Set CPU core MSR floor limit frequency.

This function sets the MSR floor frequency limit for the specified CPU core.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU core which to set

  • msr_floor_freq – [in] - MSR floor limit frequency value to be set in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_freq_range(uint32_t *fmax, uint32_t *fmin)#

Get the CPU socket frequency range.

This function retrieves frequency limit range for CPU socket 0.

Platform:

cpu_bm

Parameters:

  • fmax – [out] - Output buffer to retrieve maximum frequency in MHz

  • fmin – [out] - Output buffer to retrieve minimum frequency in MHz

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_sdps_limit(amdsmi_processor_handle processor_handle, uint32_t sdps_limit)#

Set the SDPS(Socket DIMM Power Sloshing) limit for a given processor socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Processor handle for which to set the limit

  • sdps_limit – [in] - SDPS limit value in milliwatts

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_sdps_limit(amdsmi_processor_handle processor_handle, uint32_t *sdps_limit)#

Get the current SDPS limit for a given processor socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Processor handle for which to query the limit

  • sdps_limit – [out] - Input buffer to receive the current SDPS limit value in milliwatts (mW)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

DDR bandwidth monitor#

amdsmi_status_t amdsmi_get_cpu_ddr_bw(amdsmi_processor_handle processor_handle, amdsmi_ddr_bw_metrics_t *ddr_bw)#

Get the DDR bandwidth data.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • ddr_bw – [inout] - Input buffer to fill ddr bandwidth data

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Temperature Query#

amdsmi_status_t amdsmi_get_cpu_socket_temperature(amdsmi_processor_handle processor_handle, uint32_t *ptmon)#

Get socket temperature.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • ptmon – [inout] - Input buffer to fill temperature value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_tdelta(amdsmi_processor_handle processor_handle, uint8_t *tdelta)#

Read Thermal Delta (TDELTA) Behavior.

This API retrieves the thermal solution behavior value from the CPU socket

Thermal Behavior values returned:

  • 0: Thermal solution behavior is normal (operating within expected thermal range)

  • 1 or any other value: Thermal solution is out of expected range (thermal stress detected)

    Platform:

    cpu_bm

Parameters:

  • processor_handle – [in] CPU socket handle to query

  • tdelta – [out] - input buffer to store the thermal delta behavior value:

    • 0: Normal thermal solution behavior

    • Non-zero: Thermal solution out of expected range

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on successful register read, non-zero on failure

amdsmi_status_t amdsmi_get_cpu_svi3_vr_controller_temp(amdsmi_processor_handle processor_handle, uint32_t *rail_selection, uint32_t *rail_index, uint32_t *temp)#

Get Temperature of SVI3 VR(Voltage Rail).

This API retrieves the temperature of SVI3 voltage regulator

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU socket handle to query

  • rail_selection – [inout] - Input buffer to to store rail_selection, rail_selection: 0=HottestRail, 1=IndividualRail

  • rail_index – [inout] - Input buffer to store rail_index, rail_index must be given when rail_selection = 1 rail_index: 0->VDDCR_CPU0,1->VDDCR_CPU1,2->VDDCR_SOC,3->VDDIO,4->VDDIO_MEM_S3

  • temp – [out] - Output buffer to retrieve the temperature value

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on successful temperature read, non-zero on failure

Dimm statistics#

amdsmi_status_t amdsmi_get_cpu_dimm_temp_range_and_refresh_rate(amdsmi_processor_handle processor_handle, uint8_t dimm_addr, amdsmi_temp_range_refresh_rate_t *rate)#

Get DIMM temperature range and refresh rate.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • dimm_addr – [in] - DIMM address

  • rate – [inout] - Input buffer to fill temperature range and refresh rate value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_dimm_power_consumption(amdsmi_processor_handle processor_handle, uint8_t dimm_addr, amdsmi_dimm_power_t *dimm_pow)#

Get DIMM power consumption.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • dimm_addr – [in] - DIMM address

  • dimm_pow – [inout] - Input buffer to fill power consumption value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_dimm_thermal_sensor(amdsmi_processor_handle processor_handle, uint8_t dimm_addr, amdsmi_dimm_thermal_t *dimm_temp)#

Get DIMM thermal sensor value.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • dimm_addr – [in] - DIMM address

  • dimm_temp – [inout] - Input buffer to fill temperature value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_dimm_sb_reg(amdsmi_processor_handle processor_handle, uint32_t dimm_addr, uint32_t lid, uint32_t reg_offset, uint32_t reg_space, uint32_t *data)#

Read DIMM sideband register data.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Processor handle for the target socket

  • dimm_addr – [in] - DIMM address

  • lid – [in] - The local identifier of the device on DIMM

  • reg_offset – [in] - Register offset within the specified register space

  • reg_space – [in] - Register space selector:

    • 0: Volatile register space

    • 1: Non-volatile memory (NVM) register space

  • data – [out] - Input buffer to store the 4-byte read data from the register

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on successful register read, non-zero on failure

amdsmi_status_t amdsmi_set_cpu_dimm_sb_reg(amdsmi_processor_handle processor_handle, uint32_t dimm_addr, uint32_t lid, uint32_t reg_offset, uint32_t reg_space, uint32_t write_data)#

Write Data to DIMM Sideband Register.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Processor handle for the target socket

  • dimm_addr – [in] - DIMM address

  • lid – [in] - The local identifier of the device on DIMM

  • reg_offset – [in] - Register offset within the specified register space

  • reg_space – [in] - Register space selector:

    • 0: Volatile register space

    • 1: Non-volatile memory (NVM) register space

  • write_data – [in] - 4-byte data value to write to the target register

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on successful register write, non-zero on failure

xGMI bandwidth control#

amdsmi_status_t amdsmi_set_cpu_xgmi_width(amdsmi_processor_handle processor_handle, uint8_t min, uint8_t max)#

Set xgmi width.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • min – [in] - Minimum xgmi width to be set

  • max – [in] - maximum xgmi width to be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

GMI3 width control#

Set gmi3 link width range.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • min_link_width – [in] - minimum link width to be set.

  • max_link_width – [in] - maximum link width to be set.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Pstate selection#

amdsmi_status_t amdsmi_cpu_apb_enable(amdsmi_processor_handle processor_handle)#

Enable APB.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_cpu_apb_disable(amdsmi_processor_handle processor_handle, uint8_t pstate)#

Disable APB.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • pstate – [in] - pstate value to be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_socket_lclk_dpm_level(amdsmi_processor_handle processor_handle, uint8_t nbio_id, uint8_t min, uint8_t max)#

Set NBIO lclk dpm level value.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • nbio_id – [in] - nbio index

  • min – [in] - minimum value to be set

  • max – [in] - maximum value to be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_lclk_dpm_level(amdsmi_processor_handle processor_handle, uint8_t nbio_id, amdsmi_dpm_level_t *nbio)#

Get NBIO LCLK dpm level.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • nbio_id – [in] - nbio index

  • nbio – [inout] - Input buffer to fill lclk dpm level

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Set pcie link rate.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • rate_ctrl – [in] - rate control value to be set.

  • prev_mode – [inout] - Input buffer to fill previous rate control value.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_df_pstate_range(amdsmi_processor_handle processor_handle, uint8_t min_pstate, uint8_t max_pstate)#

Set df pstate range.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • min_pstate – [in] - minimum pstate value to be set

  • max_pstate – [in] - maximum pstate value to be set

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_xgmi_pstate_range(amdsmi_processor_handle processor_handle, uint8_t min_pstate, uint8_t max_pstate)#

Set the Min and Max XGMI PState Range.

This API configures the XGMI P-State range for the specified processor socket.

P-State range constraints:

  • min_pstate: Minimum allowed XGMI P-State

  • max_pstate: Maximum allowed XGMI P-State

  • Constraint: max_pstate <= min_pstate

    Platform:

    cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to configure

  • min_pstate – [in] - minimum XGMI P-State value

  • max_pstate – [in] - maximum XGMI P-State value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_xgmi_pstate_range(amdsmi_processor_handle processor_handle, uint8_t *min_pstate, uint8_t *max_pstate)#

Get the Max and Min XGMI PState Range.

This API retrieves the current XGMI P-State range configuration for the specified processor socket.

P-State range values returned:

  • min_pstate: Current minimum XGMI P-State setting

  • max_pstate: Current maximum XGMI P-State setting

  • Relationship: max_pstate <= min_pstate

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • min_pstate – [out] - Input buffer to store current minimum XGMI P-State value

  • max_pstate – [out] - Input buffer to store current maximum XGMI P-State value

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_pc6_enable(amdsmi_processor_handle processor_handle, uint8_t *enabled)#

Get the PC6 Enable State.

This API retrieves the current PC6 (Package C-state 6) enable state for the specified processor socket.

PC6 enable state values returned:

  • 0: PC6 disabled

  • 1: PC6 enabled

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • enabled – [out] - Input buffer to store the current PC6 enable state

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_set_cpu_pc6_enable(amdsmi_processor_handle processor_handle, uint8_t enable)#

Set the PC6 Enable State.

This API configures the PC6 (Package C-state 6) enable state for the specified processor socket.

PC6 enable state values:

  • 0: PC6 disabled

  • 1: PC6 enabled

    Platform:

    cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to configure

  • enable – [in] - PC6 enable state (0=disable, 1=enable)

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_cc6_enable(amdsmi_processor_handle processor_handle, uint8_t *enabled)#

Get the Core C6 Enable State.

This API retrieves the Core C6 (CC6) low-power state for the specified processor socket.

CC6 enable state values returned:

  • 0: CC6 state disabled

  • 1: CC6 state enabled

    Platform:

    cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • enabled – [inout] - Input buffer to store the current CC6 enable state

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success, non-zero on failure

amdsmi_status_t amdsmi_set_cpu_cc6_enable(amdsmi_processor_handle processor_handle, uint8_t enable)#

Set the Core C6 Enable State.

This API configures the Core C6 (CC6) low-power state for the specified processor socket.

CC6 enable state values:

  • 0: Disable CC6 state

  • 1: Enable CC6 state

    Platform:

    cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to configure

  • enable – [in] - CC6 enable state value:

    • 0: Disable CC6 low-power state

    • 1: Enable CC6 low-power state

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Bandwidth monitor#

amdsmi_status_t amdsmi_get_cpu_current_io_bandwidth(amdsmi_processor_handle processor_handle, amdsmi_link_id_bw_type_t link, uint32_t *io_bw)#

Get current input output bandwidth.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • link – [in] - link id and bw type to which io bandwidth to be obtained

  • io_bw – [inout] - Input buffer to fill bandwidth data

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_current_xgmi_bw(amdsmi_processor_handle processor_handle, amdsmi_link_id_bw_type_t link, uint32_t *xgmi_bw)#

Get current input output bandwidth.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • link – [in] - link id and bw type to which xgmi bandwidth to be obtained

  • xgmi_bw – [inout] - Input buffer to fill bandwidth data

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

HSMP Metrics Table#

amdsmi_status_t amdsmi_get_hsmp_metrics_table_version(amdsmi_processor_handle processor_handle, uint32_t *metrics_version)#

Get HSMP metrics table version.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • metrics_version – [inout] input buffer to return the HSMP metrics table version.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_hsmp_metrics_table(amdsmi_processor_handle processor_handle, amdsmi_hsmp_metrics_table_t *metrics_table)#

Get HSMP metrics table.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • metrics_table – [inout] input buffer to return the HSMP metrics table.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Auxiliary functions#

amdsmi_status_t amdsmi_first_online_core_on_cpu_socket(amdsmi_processor_handle processor_handle, uint32_t *pcore_ind)#

Get first online core on socket.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • pcore_ind – [inout] - Input buffer to fill first online core on socket data

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_family(uint32_t *cpu_family)#

Get CPU family.

Platform:

cpu_bm

Parameters:

  • cpu_family – [inout] - Input buffer to return the cpu family

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_model(uint32_t *cpu_model)#

Get CPU model.

Platform:

cpu_bm

Parameters:

  • cpu_model – [inout] - Input buffer to return the cpu model

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_model_name(amdsmi_processor_handle processor_handle, amdsmi_cpu_info_t *cpu_info)#

Retrieve the CPU processor model name based on the processor index.

Platform:

cpu_bm

This function obtains the CPU model name associated with the specified processor index from the list of available processor handles. Before invoking this function, ensure that the list of processor handles is properly initialized and that the processor type is specified. This function is to be utilized for RDC and is not part of ESMI library.

Parameters:

  • processor_handle – [in] Cpu socket which to query

  • cpu_info – [out] A pointer to an amdsmi_cpu_info_t structure that will be populated with the CPU processor model information upon successful execution of the function.

Returns:

amdsmi_status_t indicating the result of the operation.

  • AMDSMI_STATUS_SUCCESS on successful retrieval of the model name.

  • A non-zero error code if the operation fails.

amdsmi_status_t amdsmi_get_esmi_err_msg(amdsmi_status_t status, const char **status_string)#

Get a description of provided AMDSMI error status for esmi errors.

Platform:

cpu_bm

Set the provided pointer to a const char *, status_string, to a string containing a description of the provided error code status.

Parameters:

  • status – [in] - The error status for which a description is desired.

  • status_string – [inout] - A pointer to a const char * which will be made to point to a description of the provided error code

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_cores_per_socket(uint32_t sock_count, amdsmi_sock_info_t *soc_info)#

Get cpu cores per socket from sys filesystem.

Platform:

cpu_bm

Parameters:

  • sock_count – [in] - cpu socket count

  • soc_info – [inout] - Input buffer to return the cpu cores per socket

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_socket_count(uint32_t *sock_count)#

Get CPU socket count from sys filesystem.

Platform:

cpu_bm

Parameters:

  • sock_count – [inout] - Input buffer to return the cpu socket count

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_cpu_enabled_commands(amdsmi_processor_handle processor_handle, bool *r_mask, uint32_t *mask0, uint32_t *mask1, uint32_t *mask2)#

Get HSMP Enabled Commands information for a given CPU socket.

This function retrieves enabled commands bit masks for both read and write commands from the HSMP interface.

Platform:

cpu_bm

Parameters:

  • processor_handle – [in] CPU socket handle to query

  • r_mask – [in] - Input buffer to store read mask, indicating read or write enabled commands to query

  • mask0 – [inout] - Input buffer to store read/write enabled hsmp command mask0

  • mask1 – [inout] - Input buffer to store read/write enabled hsmp command mask1

  • mask2 – [inout] - Input buffer to store read/write enabled hsmp command mask2

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

NIC Information#

amdsmi_status_t amdsmi_get_nic_driver_info(amdsmi_processor_handle processor_handle, amdsmi_nic_driver_info_t *info)#

Retrieves information about the NIC driver.

Platform:

host

gpu_bm_linux

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic driver info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_asic_info(amdsmi_processor_handle processor_handle, amdsmi_nic_asic_info_t *info)#

Retrieves ASIC information for the NIC.

Platform:

host

gpu_bm_linux

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic asic info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_bus_info(amdsmi_processor_handle processor_handle, amdsmi_nic_bus_info_t *info)#

Retrieves BUS information for the NIC.

Platform:

host

gpu_bm_linux

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic bus info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_numa_info(amdsmi_processor_handle processor_handle, amdsmi_nic_numa_info_t *info)#

Retrieves NUMA information for the NIC.

Platform:

host

gpu_bm_linux

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic numa info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_port_info(amdsmi_processor_handle processor_handle, amdsmi_nic_port_info_t *info)#

Retrieves PORT information for the NIC.

Platform:

host

gpu_bm_linux

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic port info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_rdma_dev_info(amdsmi_processor_handle processor_handle, amdsmi_nic_rdma_devices_info_t *info)#

Retrieves RDMA devices information for the NIC.

Platform:

host

gpu_bm_linux

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic rdma devices info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_rdma_port_statistics(amdsmi_processor_handle processor_handle, uint32_t rdma_port_index, uint32_t *num_stats, amdsmi_nic_stat_t *stats)#

Retrieve RDMA port statistics for the NIC.

Platform:

host

gpu_bm_linux

This function follows a two-call pattern:

  1. First call with stats=NULL to get the count of available statistics

  2. Second call with allocated array to retrieve all statistics

Parameters:

  • processor_handle – [in] NIC for which to query

  • rdma_port_index – [in] index of the NIC RDMA port to query

  • num_stats – [inout] pointer to the number of statistics

    • Input: maximum number of statistics that stats array can hold

    • Output: actual number of statistics available/returned

  • stats – [out] pointer to array of amdsmi_nic_stat_t structures to be filled

    • If NULL, only num_stats is filled with the count of available statistics

    • If not NULL, must be allocated by user with at least num_stats elements

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_fw_info(amdsmi_processor_handle processor_handle, amdsmi_nic_fw_info_t *info)#

Retrieves firmware version information for the NIC.

Platform:

host

gpu_bm_linux

Note

This API depends on libmnl. If libmnl is not installed on the system, this function returns AMDSMI_STATUS_NOT_SUPPORTED.

Parameters:

  • processor_handle – [in] NIC for which to query

  • info – [out] reference to the nic firmware info struct. Must be allocated by user.

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_port_statistics(amdsmi_processor_handle processor_handle, uint32_t port_index, uint32_t *num_stats, amdsmi_nic_stat_t *stats)#

Retrieve PORT statistics for the specified NIC port.

Platform:

host

gpu_bm_linux

This function follows a two-call pattern:

  1. First call with stats=NULL to get the count of available statistics

  2. Second call with allocated array to retrieve all statistics

Parameters:

  • processor_handle – [in] NIC for which to query

  • port_index – [in] index of the NIC port to query

  • num_stats – [inout] pointer to the number of statistics

    • Input: maximum number of statistics that stats array can hold

    • Output: actual number of statistics available/returned

  • stats – [out] pointer to array of amdsmi_nic_stat_t structures to be filled

    • If NULL, only num_stats is filled with the count of available statistics

    • If not NULL, must be allocated by user with at least num_stats elements

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

amdsmi_status_t amdsmi_get_nic_vendor_statistics(amdsmi_processor_handle processor_handle, uint32_t port_index, uint32_t *num_stats, amdsmi_nic_stat_t *stats)#

Retrieve vendor specific statistics for the NIC port.

Platform:

host

gpu_bm_linux

This function follows a two-call pattern:

  1. First call with stats=NULL to get the count of available statistics

  2. Second call with allocated array to retrieve all statistics

This API provides access to vendor/driver specific statistics that may vary between different NIC vendors and driver/fw versions. The statistic names are preserved as provided by the underlying driver implementation.

Parameters:

  • processor_handle – [in] NIC for which to query

  • port_index – [in] index of the NIC port to query

  • num_stats – [inout] pointer to the number of statistics

    • Input: maximum number of statistics that stats array can hold

    • Output: actual number of statistics available/returned

  • stats – [out] pointer to array of amdsmi_nic_stat_t structures to be filled

    • If NULL, only num_stats is filled with the count of available statistics

    • If not NULL, must be allocated by user with at least num_stats elements

Returns:

amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

Memory Configuration#

amdsmi_status_t amdsmi_get_gpu_uma_carveout_info(amdsmi_processor_handle processor_handle, amdsmi_uma_carveout_info_t *info)#

Get UMA carveout configuration information.

This function retrieves the current UMA (Unified Memory Architecture) carveout configuration for the specified GPU. UMA carveout controls dedicated GPU memory allocation on APU systems.

Platform:

gpu_bm_linux

Note

This uses a kernel UAPI sysfs interface, not libdrm.

Parameters:

  • processor_handle – [in] GPU device handle

  • info – [out] Pointer to receive UMA carveout information

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success AMDSMI_STATUS_NOT_SUPPORTED if UMA carveout is not available on this device AMDSMI_STATUS_INVAL if info is nullptr

amdsmi_status_t amdsmi_set_gpu_uma_carveout(amdsmi_processor_handle processor_handle, uint32_t option_index)#

Set UMA carveout configuration.

This function sets the UMA carveout configuration for the specified GPU. The system must be rebooted for changes to take effect.

Platform:

gpu_bm_linux

Note

This uses a kernel UAPI sysfs interface, not libdrm.

Parameters:

  • processor_handle – [in] GPU device handle

  • option_index – [in] Index of the carveout option to set

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success AMDSMI_STATUS_NOT_SUPPORTED if UMA carveout is not available on this device AMDSMI_STATUS_NO_PERM if insufficient permissions AMDSMI_STATUS_INVAL if option_index is out of range

amdsmi_status_t amdsmi_get_ttm_info(amdsmi_ttm_info_t *info)#

Get TTM configuration information.

This function retrieves the current TTM (Translation Table Manager) pages limit. TTM controls shared GPU memory (GTT) allocation.

Platform:

gpu_bm_linux

Note

This uses a kernel UAPI interface (modprobe.d), not libdrm.

Parameters:

  • info – [out] Pointer to receive TTM configuration information

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success AMDSMI_STATUS_NOT_SUPPORTED if TTM configuration is not available AMDSMI_STATUS_INVAL if info is nullptr

amdsmi_status_t amdsmi_set_ttm_pages_limit(uint64_t pages)#

Set TTM pages limit.

This function configures the TTM pages limit by creating/updating /etc/modprobe.d/ttm.conf. The system must be rebooted for changes to take effect.

Platform:

gpu_bm_linux

Note

This uses a kernel UAPI interface (modprobe.d), not libdrm.

Parameters:

  • pages – [in] Number of pages to allocate for TTM

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success AMDSMI_STATUS_NO_PERM if insufficient permissions AMDSMI_STATUS_INVAL if pages is 0

amdsmi_status_t amdsmi_reset_ttm_pages_limit(void)#

Reset TTM pages limit to system default.

This function resets the TTM pages limit to system default by removing /etc/modprobe.d/ttm.conf. The system must be rebooted for changes to take effect.

Platform:

gpu_bm_linux

Note

This uses a kernel UAPI interface (modprobe.d), not libdrm.

Returns:

amdsmi_status_t AMDSMI_STATUS_SUCCESS on success AMDSMI_STATUS_NO_PERM if insufficient permissions

AMDSMI_MAX_CARVEOUT_OPTIONS

Maximum carveout options.

Maximum number of UMA carveout options

struct amdsmi_uma_carveout_option_t#
#include <amdsmi.h>

UMA carveout option descriptor

struct amdsmi_uma_carveout_info_t#
#include <amdsmi.h>

UMA carveout configuration information

struct amdsmi_ttm_info_t#
#include <amdsmi.h>

TTM (Translation Table Manager) configuration information

Contents