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://docs.amd.com/v/u/en-US/55898_B1_pub_0_50 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 71The sysfs metrics_bin path supports only HSMP protocol version 6 and, 72because it is a file read, can return a torn snapshot if userspace 73reads in pieces. The protocol version 7 metric table (~13 KB) also 74exceeds PAGE_SIZE, so a read returns ``-EOPNOTSUPP`` there. For 75atomic reads on any protocol version, use the 76``HSMP_IOCTL_GET_TELEMETRY_DATA`` ioctl on /dev/hsmp (see below). 77 78Metrics table definitions will be documented as part of Public PPR. 79The same is defined in the amd_hsmp.h header. 80 812. HSMP telemetry sysfs files 82 83Following sysfs files are available at /sys/devices/platform/AMDI0097:0X/. 84 85* c0_residency_input: Percentage of cores in C0 state. 86* prochot_status: Reports 1 if the processor is at thermal threshold value, 87 0 otherwise. 88* smu_fw_version: SMU firmware version. 89* protocol_version: HSMP interface version. 90* ddr_max_bw: Theoretical maximum DDR bandwidth in GB/s. 91* ddr_utilised_bw_input: Current utilized DDR bandwidth in GB/s. 92* ddr_utilised_bw_perc_input(%): Percentage of current utilized DDR bandwidth. 93* mclk_input: Memory clock in MHz. 94* fclk_input: Fabric clock in MHz. 95* clk_fmax: Maximum frequency of socket in MHz. 96* clk_fmin: Minimum frequency of socket in MHz. 97* cclk_freq_limit_input: Core clock frequency limit per socket in MHz. 98* pwr_current_active_freq_limit: Current active frequency limit of socket 99 in MHz. 100* pwr_current_active_freq_limit_source: Source of current active frequency 101 limit. 102 103ACPI device object format 104========================= 105The ACPI object format expected from the amd_hsmp driver 106for socket with ID00 is given below:: 107 108 Device(HSMP) 109 { 110 Name(_HID, "AMDI0097") 111 Name(_UID, "ID00") 112 Name(HSE0, 0x00000001) 113 Name(RBF0, ResourceTemplate() 114 { 115 Memory32Fixed(ReadWrite, 0xxxxxxx, 0x00100000) 116 }) 117 Method(_CRS, 0, NotSerialized) 118 { 119 Return(RBF0) 120 } 121 Method(_STA, 0, NotSerialized) 122 { 123 If(LEqual(HSE0, One)) 124 { 125 Return(0x0F) 126 } 127 Else 128 { 129 Return(Zero) 130 } 131 } 132 Name(_DSD, Package(2) 133 { 134 Buffer(0x10) 135 { 136 0x9D, 0x61, 0x4D, 0xB7, 0x07, 0x57, 0xBD, 0x48, 137 0xA6, 0x9F, 0x4E, 0xA2, 0x87, 0x1F, 0xC2, 0xF6 138 }, 139 Package(3) 140 { 141 Package(2) {"MsgIdOffset", 0x00010934}, 142 Package(2) {"MsgRspOffset", 0x00010980}, 143 Package(2) {"MsgArgOffset", 0x000109E0} 144 } 145 }) 146 } 147 148HSMP HWMON interface 149==================== 150HSMP power sensors are registered with the hwmon interface. A separate hwmon 151directory is created for each socket and the following files are generated 152within the hwmon directory. 153- power1_input (read only) 154- power1_cap_max (read only) 155- power1_cap (read, write) 156 157An example 158========== 159 160To access hsmp device from a C program. 161First, you need to include the headers:: 162 163 #include <linux/amd_hsmp.h> 164 165Which defines the supported messages/message IDs. 166 167Next thing, open the device file, as follows:: 168 169 int file; 170 171 file = open("/dev/hsmp", O_RDWR); 172 if (file < 0) { 173 /* ERROR HANDLING; you can check errno to see what went wrong */ 174 exit(1); 175 } 176 177The following IOCTLs are defined: 178 179``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)`` 180 The argument is a pointer to a:: 181 182 struct hsmp_message { 183 __u32 msg_id; /* Message ID */ 184 __u16 num_args; /* Number of input argument words in message */ 185 __u16 response_sz; /* Number of expected output/response words */ 186 __u32 args[HSMP_MAX_MSG_LEN]; /* argument/response buffer */ 187 __u16 sock_ind; /* socket number */ 188 }; 189 190``ioctl(file, HSMP_IOCTL_GET_TELEMETRY_DATA, struct hsmp_telemetry_data *req)`` 191 Atomically fetch the firmware metric (telemetry) table for a socket. 192 The ioctl copies the table in one shot, so unlike the metrics_bin 193 sysfs path it cannot return a torn snapshot and is not bounded by 194 PAGE_SIZE. Required for HSMP protocol version 7+ (e.g. Family 1Ah 195 Model 50h-5Fh, whose table is ~13 KB). Argument:: 196 197 struct hsmp_telemetry_data { 198 __u64 buf; /* User pointer to destination buffer */ 199 __u32 size; /* Size of @buf in bytes */ 200 __u16 sock_ind; /* Socket index */ 201 __u16 reserved; /* Reserved, must be zero */ 202 }; 203 204 ``size`` must be non-zero and no larger than the table size firmware 205 reports for that socket; a larger value is rejected with ``-EINVAL`` 206 rather than short-written, and a smaller one returns the leading 207 ``size`` bytes of the snapshot. A non-zero ``reserved`` is also 208 rejected with ``-EINVAL``. 209 210 The table layout depends on the protocol version, which userspace 211 reads from the ``protocol_version`` sysfs attribute. On version 6 212 the table is ``struct hsmp_metric_table``, so callers pass 213 ``sizeof(struct hsmp_metric_table)``. Later version metrics table 214 layout is documented in the Public PPR. 215 216The ioctl would return a non-zero on failure; you can read errno to see 217what happened. The transaction returns 0 on success. 218 219More details on the interface and message definitions can be found in chapter 220"7 Host System Management Port (HSMP)" of the respective family/model PPR 221eg: https://docs.amd.com/v/u/en-US/55898_B1_pub_0_50 222 223User space C-APIs are made available by linking against the esmi library, 224which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html. 225See: https://github.com/amd/esmi_ib_library 226