xref: /linux/Documentation/arch/x86/amd_hsmp.rst (revision fcb3ad4366b9c810cbb9da34c076a9a52d8aa1e0)
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