|
| 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 |
0 commit comments