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/system/files/TechDocs/55898_B1_pub_0.50.zip
17
18HSMP interface is supported on EPYC server CPU models only.
19
20
21HSMP device
22============================================
23
24amd_hsmp driver under the drivers/platforms/x86/ creates miscdevice
25/dev/hsmp to let user space programs run hsmp mailbox commands.
26
27$ ls -al /dev/hsmp
28crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp
29
30Characteristics of the dev node:
31 * Write mode is used for running set/configure commands
32 * Read mode is used for running get/status monitor commands
33
34Access restrictions:
35 * Only root user is allowed to open the file in write mode.
36 * The file can be opened in read mode by all the users.
37
38In-kernel integration:
39 * Other subsystems in the kernel can use the exported transport
40   function hsmp_send_message().
41 * Locking across callers is taken care by the driver.
42
43
44An example
45==========
46
47To access hsmp device from a C program.
48First, you need to include the headers::
49
50  #include <linux/amd_hsmp.h>
51
52Which defines the supported messages/message IDs.
53
54Next thing, open the device file, as follows::
55
56  int file;
57
58  file = open("/dev/hsmp", O_RDWR);
59  if (file < 0) {
60    /* ERROR HANDLING; you can check errno to see what went wrong */
61    exit(1);
62  }
63
64The following IOCTL is defined:
65
66``ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)``
67  The argument is a pointer to a::
68
69    struct hsmp_message {
70    	__u32	msg_id;				/* Message ID */
71    	__u16	num_args;			/* Number of input argument words in message */
72    	__u16	response_sz;			/* Number of expected output/response words */
73    	__u32	args[HSMP_MAX_MSG_LEN];		/* argument/response buffer */
74    	__u16	sock_ind;			/* socket number */
75    };
76
77The ioctl would return a non-zero on failure; you can read errno to see
78what happened. The transaction returns 0 on success.
79
80More details on the interface and message definitions can be found in chapter
81"7 Host System Management Port (HSMP)" of the respective family/model PPR
82eg: https://www.amd.com/system/files/TechDocs/55898_B1_pub_0.50.zip
83
84User space C-APIs are made available by linking against the esmi library,
85which is provided by the E-SMS project https://developer.amd.com/e-sms/.
86See: https://github.com/amd/esmi_ib_library
87