Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: Add x86/amd_hsmp driver
This documentation for amd_hsmp driver explains how to use the
device interface.
Signed-off-by: Naveen Krishna Chatradhi <nchatrad@amd.com>
Acked-by: Song Liu <song@kernel.org>
Link: https://lore.kernel.org/r/20220222050501.18789-2-nchatrad@amd.com
Reviewed-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
authored by
Naveen Krishna Chatradhi
and committed by
Hans de Goede
402576d9
91f410aa
+87
+86
Documentation/x86/amd_hsmp.rst
+86
Documentation/x86/amd_hsmp.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
============================================
4
+
AMD HSMP interface
5
+
============================================
6
+
7
+
Newer Fam19h EPYC server line of processors from AMD support system
8
+
management functionality via HSMP (Host System Management Port).
9
+
10
+
The Host System Management Port (HSMP) is an interface to provide
11
+
OS-level software with access to system management functions via a
12
+
set of mailbox registers.
13
+
14
+
More details on the interface can be found in chapter
15
+
"7 Host System Management Port (HSMP)" of the family/model PPR
16
+
Eg: https://www.amd.com/system/files/TechDocs/55898_B1_pub_0.50.zip
17
+
18
+
HSMP interface is supported on EPYC server CPU models only.
19
+
20
+
21
+
HSMP device
22
+
============================================
23
+
24
+
amd_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
28
+
crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp
29
+
30
+
Characteristics 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
+
34
+
Access 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
+
38
+
In-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
+
44
+
An example
45
+
==========
46
+
47
+
To access hsmp device from a C program.
48
+
First, you need to include the headers::
49
+
50
+
#include <linux/amd_hsmp.h>
51
+
52
+
Which defines the supported messages/message IDs.
53
+
54
+
Next 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
+
64
+
The 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
+
77
+
The ioctl would return a non-zero on failure; you can read errno to see
78
+
what happened. The transaction returns 0 on success.
79
+
80
+
More 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
82
+
eg: https://www.amd.com/system/files/TechDocs/55898_B1_pub_0.50.zip
83
+
84
+
User space C-APIs are made available by linking against the esmi library,
85
+
which is provided by the E-SMS project https://developer.amd.com/e-sms/.
86
+
See: https://github.com/amd/esmi_ib_library