1.. SPDX-License-Identifier: GPL-2.0 2 3============================================ 4AMD HSMP interface 5============================================ 6 7Newer Fam19h(model 0x00-0x1f, 0x30-0x3f, 0x90-0x9f, 0xa0-0xaf), 8Fam1Ah(model 0x00-0x1f) EPYC server line of processors from AMD support 9system management functionality via HSMP (Host System Management Port). 10 11The Host System Management Port (HSMP) is an interface to provide 12OS-level software with access to system management functions via a 13set of mailbox registers. 14 15More details on the interface can be found in chapter 16"7 Host System Management Port (HSMP)" of the family/model PPR 17Eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip 18 19 20HSMP interface is supported on EPYC line of server CPUs and MI300A (APU). 21 22 23HSMP device 24============================================ 25 26amd_hsmp driver under drivers/platforms/x86/amd/hsmp/ has separate driver files 27for ACPI object based probing, platform device based probing and for the common 28code for these two drivers. 29 30Kconfig option CONFIG_AMD_HSMP_PLAT compiles plat.c and creates amd_hsmp.ko. 31Kconfig option CONFIG_AMD_HSMP_ACPI compiles acpi.c and creates hsmp_acpi.ko. 32Selecting any of these two configs automatically selects CONFIG_AMD_HSMP. This 33compiles common code hsmp.c and creates hsmp_common.ko module. 34 35Both the ACPI and plat drivers create the miscdevice /dev/hsmp to let 36user space programs run hsmp mailbox commands. 37 38The ACPI object format supported by the driver is defined below. 39 40$ ls -al /dev/hsmp 41crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp 42 43Characteristics of the dev node: 44 * Write mode is used for running set/configure commands 45 * Read mode is used for running get/status monitor commands 46 47Access restrictions: 48 * Only root user is allowed to open the file in write mode. 49 * The file can be opened in read mode by all the users. 50 51In-kernel integration: 52 * Other subsystems in the kernel can use the exported transport 53 function hsmp_send_message(). 54 * Locking across callers is taken care by the driver. 55 56 57HSMP sysfs interface 58==================== 59 601. Metrics table binary sysfs 61 62AMD MI300A MCM provides GET_METRICS_TABLE message to retrieve 63most of the system management information from SMU in one go. 64 65The metrics table is made available as hexadecimal sysfs binary file 66under per socket sysfs directory created at 67/sys/devices/platform/amd_hsmp/socket%d/metrics_bin 68 69Note: lseek() is not supported as entire metrics table is read. 70 71Metrics table definitions will be documented as part of Public PPR. 72The same is defined in the amd_hsmp.h header. 73 742. HSMP telemetry sysfs files 75 76Following sysfs files are available at /sys/devices/platform/AMDI0097:0X/. 77 78* c0_residency_input: Percentage of cores in C0 state. 79* prochot_status: Reports 1 if the processor is at thermal threshold value, 80 0 otherwise. 81* smu_fw_version: SMU firmware version. 82* protocol_version: HSMP interface version. 83* ddr_max_bw: Theoretical maximum DDR bandwidth in GB/s. 84* ddr_utilised_bw_input: Current utilized DDR bandwidth in GB/s. 85* ddr_utilised_bw_perc_input(%): Percentage of current utilized DDR bandwidth. 86* mclk_input: Memory clock in MHz. 87* fclk_input: Fabric clock in MHz. 88* clk_fmax: Maximum frequency of socket in MHz. 89* clk_fmin: Minimum frequency of socket in MHz. 90* cclk_freq_limit_input: Core clock frequency limit per socket in MHz. 91* pwr_current_active_freq_limit: Current active frequency limit of socket 92 in MHz. 93* pwr_current_active_freq_limit_source: Source of current active frequency 94 limit. 95 96ACPI device object format 97========================= 98The ACPI object format expected from the amd_hsmp driver 99for socket with ID00 is given below:: 100 101 Device(HSMP) 102 { 103 Name(_HID, "AMDI0097") 104 Name(_UID, "ID00") 105 Name(HSE0, 0x00000001) 106 Name(RBF0, ResourceTemplate() 107 { 108 Memory32Fixed(ReadWrite, 0xxxxxxx, 0x00100000) 109 }) 110 Method(_CRS, 0, NotSerialized) 111 { 112 Return(RBF0) 113 } 114 Method(_STA, 0, NotSerialized) 115 { 116 If(LEqual(HSE0, One)) 117 { 118 Return(0x0F) 119 } 120 Else 121 { 122 Return(Zero) 123 } 124 } 125 Name(_DSD, Package(2) 126 { 127 Buffer(0x10) 128 { 129 0x9D, 0x61, 0x4D, 0xB7, 0x07, 0x57, 0xBD, 0x48, 130 0xA6, 0x9F, 0x4E, 0xA2, 0x87, 0x1F, 0xC2, 0xF6 131 }, 132 Package(3) 133 { 134 Package(2) {"MsgIdOffset", 0x00010934}, 135 Package(2) {"MsgRspOffset", 0x00010980}, 136 Package(2) {"MsgArgOffset", 0x000109E0} 137 } 138 }) 139 } 140 141HSMP HWMON interface 142==================== 143HSMP power sensors are registered with the hwmon interface. A separate hwmon 144directory is created for each socket and the following files are generated 145within the hwmon directory. 146- power1_input (read only) 147- power1_cap_max (read only) 148- power1_cap (read, write) 149 150An example 151========== 152 153To access hsmp device from a C program. 154First, you need to include the headers:: 155 156 #include <linux/amd_hsmp.h> 157 158Which defines the supported messages/message IDs. 159 160Next thing, open the device file, as follows:: 161 162 int file; 163 164 file = open("/dev/hsmp", O_RDWR); 165 if (file < 0) { 166 /* ERROR HANDLING; you can check errno to see what went wrong */ 167 exit(1); 168 } 169 170The following IOCTL is defined: 171 172``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)`` 173 The argument is a pointer to a:: 174 175 struct hsmp_message { 176 __u32 msg_id; /* Message ID */ 177 __u16 num_args; /* Number of input argument words in message */ 178 __u16 response_sz; /* Number of expected output/response words */ 179 __u32 args[HSMP_MAX_MSG_LEN]; /* argument/response buffer */ 180 __u16 sock_ind; /* socket number */ 181 }; 182 183The ioctl would return a non-zero on failure; you can read errno to see 184what happened. The transaction returns 0 on success. 185 186More details on the interface and message definitions can be found in chapter 187"7 Host System Management Port (HSMP)" of the respective family/model PPR 188eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip 189 190User space C-APIs are made available by linking against the esmi library, 191which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html. 192See: https://github.com/amd/esmi_ib_library 193