1.. SPDX-License-Identifier: GPL-2.0 2 3============================================ 4AMD HSMP interface 5============================================ 6 7Newer Fam19h EPYC server line of processors from AMD support system 8management functionality via HSMP (Host System Management Port). 9 10The Host System Management Port (HSMP) is an interface to provide 11OS-level software with access to system management functions via a 12set of mailbox registers. 13 14More details on the interface can be found in chapter 15"7 Host System Management Port (HSMP)" of the family/model PPR 16Eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip 17 18 19HSMP interface is supported on EPYC server CPU models only. 20 21 22HSMP device 23============================================ 24 25amd_hsmp driver under the drivers/platforms/x86/ creates miscdevice 26/dev/hsmp to let user space programs run hsmp mailbox commands. 27 28$ ls -al /dev/hsmp 29crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp 30 31Characteristics of the dev node: 32 * Write mode is used for running set/configure commands 33 * Read mode is used for running get/status monitor commands 34 35Access restrictions: 36 * Only root user is allowed to open the file in write mode. 37 * The file can be opened in read mode by all the users. 38 39In-kernel integration: 40 * Other subsystems in the kernel can use the exported transport 41 function hsmp_send_message(). 42 * Locking across callers is taken care by the driver. 43 44 45HSMP sysfs interface 46==================== 47 481. Metrics table binary sysfs 49 50AMD MI300A MCM provides GET_METRICS_TABLE message to retrieve 51most of the system management information from SMU in one go. 52 53The metrics table is made available as hexadecimal sysfs binary file 54under per socket sysfs directory created at 55/sys/devices/platform/amd_hsmp/socket%d/metrics_bin 56 57Note: lseek() is not supported as entire metrics table is read. 58 59Metrics table definitions will be documented as part of Public PPR. 60The same is defined in the amd_hsmp.h header. 61 62 63An example 64========== 65 66To access hsmp device from a C program. 67First, you need to include the headers:: 68 69 #include <linux/amd_hsmp.h> 70 71Which defines the supported messages/message IDs. 72 73Next thing, open the device file, as follows:: 74 75 int file; 76 77 file = open("/dev/hsmp", O_RDWR); 78 if (file < 0) { 79 /* ERROR HANDLING; you can check errno to see what went wrong */ 80 exit(1); 81 } 82 83The following IOCTL is defined: 84 85``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)`` 86 The argument is a pointer to a:: 87 88 struct hsmp_message { 89 __u32 msg_id; /* Message ID */ 90 __u16 num_args; /* Number of input argument words in message */ 91 __u16 response_sz; /* Number of expected output/response words */ 92 __u32 args[HSMP_MAX_MSG_LEN]; /* argument/response buffer */ 93 __u16 sock_ind; /* socket number */ 94 }; 95 96The ioctl would return a non-zero on failure; you can read errno to see 97what happened. The transaction returns 0 on success. 98 99More details on the interface and message definitions can be found in chapter 100"7 Host System Management Port (HSMP)" of the respective family/model PPR 101eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip 102 103User space C-APIs are made available by linking against the esmi library, 104which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html. 105See: https://github.com/amd/esmi_ib_library 106