0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ============================================
0004 AMD HSMP interface
0005 ============================================
0006
0007 Newer Fam19h EPYC server line of processors from AMD support system
0008 management functionality via HSMP (Host System Management Port).
0009
0010 The Host System Management Port (HSMP) is an interface to provide
0011 OS-level software with access to system management functions via a
0012 set of mailbox registers.
0013
0014 More details on the interface can be found in chapter
0015 "7 Host System Management Port (HSMP)" of the family/model PPR
0016 Eg: https://www.amd.com/system/files/TechDocs/55898_B1_pub_0.50.zip
0017
0018 HSMP interface is supported on EPYC server CPU models only.
0019
0020
0021 HSMP device
0022 ============================================
0023
0024 amd_hsmp driver under the drivers/platforms/x86/ creates miscdevice
0025 /dev/hsmp to let user space programs run hsmp mailbox commands.
0026
0027 $ ls -al /dev/hsmp
0028 crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp
0029
0030 Characteristics of the dev node:
0031 * Write mode is used for running set/configure commands
0032 * Read mode is used for running get/status monitor commands
0033
0034 Access restrictions:
0035 * Only root user is allowed to open the file in write mode.
0036 * The file can be opened in read mode by all the users.
0037
0038 In-kernel integration:
0039 * Other subsystems in the kernel can use the exported transport
0040 function hsmp_send_message().
0041 * Locking across callers is taken care by the driver.
0042
0043
0044 An example
0045 ==========
0046
0047 To access hsmp device from a C program.
0048 First, you need to include the headers::
0049
0050 #include <linux/amd_hsmp.h>
0051
0052 Which defines the supported messages/message IDs.
0053
0054 Next thing, open the device file, as follows::
0055
0056 int file;
0057
0058 file = open("/dev/hsmp", O_RDWR);
0059 if (file < 0) {
0060 /* ERROR HANDLING; you can check errno to see what went wrong */
0061 exit(1);
0062 }
0063
0064 The following IOCTL is defined:
0065
0066 ``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)``
0067 The argument is a pointer to a::
0068
0069 struct hsmp_message {
0070 __u32 msg_id; /* Message ID */
0071 __u16 num_args; /* Number of input argument words in message */
0072 __u16 response_sz; /* Number of expected output/response words */
0073 __u32 args[HSMP_MAX_MSG_LEN]; /* argument/response buffer */
0074 __u16 sock_ind; /* socket number */
0075 };
0076
0077 The ioctl would return a non-zero on failure; you can read errno to see
0078 what happened. The transaction returns 0 on success.
0079
0080 More details on the interface and message definitions can be found in chapter
0081 "7 Host System Management Port (HSMP)" of the respective family/model PPR
0082 eg: https://www.amd.com/system/files/TechDocs/55898_B1_pub_0.50.zip
0083
0084 User space C-APIs are made available by linking against the esmi library,
0085 which is provided by the E-SMS project https://developer.amd.com/e-sms/.
0086 See: https://github.com/amd/esmi_ib_library
