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 74ACPI device object format 75========================= 76The ACPI object format expected from the amd_hsmp driver 77for socket with ID00 is given below:: 78 79 Device(HSMP) 80 { 81 Name(_HID, "AMDI0097") 82 Name(_UID, "ID00") 83 Name(HSE0, 0x00000001) 84 Name(RBF0, ResourceTemplate() 85 { 86 Memory32Fixed(ReadWrite, 0xxxxxxx, 0x00100000) 87 }) 88 Method(_CRS, 0, NotSerialized) 89 { 90 Return(RBF0) 91 } 92 Method(_STA, 0, NotSerialized) 93 { 94 If(LEqual(HSE0, One)) 95 { 96 Return(0x0F) 97 } 98 Else 99 { 100 Return(Zero) 101 } 102 } 103 Name(_DSD, Package(2) 104 { 105 Buffer(0x10) 106 { 107 0x9D, 0x61, 0x4D, 0xB7, 0x07, 0x57, 0xBD, 0x48, 108 0xA6, 0x9F, 0x4E, 0xA2, 0x87, 0x1F, 0xC2, 0xF6 109 }, 110 Package(3) 111 { 112 Package(2) {"MsgIdOffset", 0x00010934}, 113 Package(2) {"MsgRspOffset", 0x00010980}, 114 Package(2) {"MsgArgOffset", 0x000109E0} 115 } 116 }) 117 } 118 119 120An example 121========== 122 123To access hsmp device from a C program. 124First, you need to include the headers:: 125 126 #include <linux/amd_hsmp.h> 127 128Which defines the supported messages/message IDs. 129 130Next thing, open the device file, as follows:: 131 132 int file; 133 134 file = open("/dev/hsmp", O_RDWR); 135 if (file < 0) { 136 /* ERROR HANDLING; you can check errno to see what went wrong */ 137 exit(1); 138 } 139 140The following IOCTL is defined: 141 142``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)`` 143 The argument is a pointer to a:: 144 145 struct hsmp_message { 146 __u32 msg_id; /* Message ID */ 147 __u16 num_args; /* Number of input argument words in message */ 148 __u16 response_sz; /* Number of expected output/response words */ 149 __u32 args[HSMP_MAX_MSG_LEN]; /* argument/response buffer */ 150 __u16 sock_ind; /* socket number */ 151 }; 152 153The ioctl would return a non-zero on failure; you can read errno to see 154what happened. The transaction returns 0 on success. 155 156More details on the interface and message definitions can be found in chapter 157"7 Host System Management Port (HSMP)" of the respective family/model PPR 158eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip 159 160User space C-APIs are made available by linking against the esmi library, 161which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html. 162See: https://github.com/amd/esmi_ib_library 163