Documentation/arch/x86/amd_hsmp.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============================================
   4 AMD HSMP interface
   5 ============================================
   6
   7 Newer Fam19h(model 0x00-0x1f, 0x30-0x3f, 0x90-0x9f, 0xa0-0xaf),
   8 Fam1Ah(model 0x00-0x1f) EPYC server line of processors from AMD support
   9 system management functionality via HSMP (Host System Management Port).
  10
  11 The Host System Management Port (HSMP) is an interface to provide
  12 OS-level software with access to system management functions via a
  13 set of mailbox registers.
  14
  15 More details on the interface can be found in chapter
  16 "7 Host System Management Port (HSMP)" of the family/model PPR
  17 Eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip
  18
  19
  20 HSMP interface is supported on EPYC line of server CPUs and MI300A (APU).
  21
  22
  23 HSMP device
  24 ============================================
  25
  26 amd_hsmp driver under drivers/platforms/x86/amd/hsmp/ has separate driver files
  27 for ACPI object based probing, platform device based probing and for the common
  28 code for these two drivers.
  29
  30 Kconfig option CONFIG_AMD_HSMP_PLAT compiles plat.c and creates amd_hsmp.ko.
  31 Kconfig option CONFIG_AMD_HSMP_ACPI compiles acpi.c and creates hsmp_acpi.ko.
  32 Selecting any of these two configs automatically selects CONFIG_AMD_HSMP. This
  33 compiles common code hsmp.c and creates hsmp_common.ko module.
  34
  35 Both the ACPI and plat drivers create the miscdevice /dev/hsmp to let
  36 user space programs run hsmp mailbox commands.
  37
  38 The ACPI object format supported by the driver is defined below.
  39
  40 $ ls -al /dev/hsmp
  41 crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp
  42
  43 Characteristics 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
  47 Access 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
  51 In-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
  57 HSMP sysfs interface
  58 ====================
  59
  60 1. Metrics table binary sysfs
  61
  62 AMD MI300A MCM provides GET_METRICS_TABLE message to retrieve
  63 most of the system management information from SMU in one go.
  64
  65 The metrics table is made available as hexadecimal sysfs binary file
  66 under per socket sysfs directory created at
  67 /sys/devices/platform/amd_hsmp/socket%d/metrics_bin
  68
  69 Note: lseek() is not supported as entire metrics table is read.
  70
  71 Metrics table definitions will be documented as part of Public PPR.
  72 The same is defined in the amd_hsmp.h header.
  73
  74 ACPI device object format
  75 =========================
  76 The ACPI object format expected from the amd_hsmp driver
  77 for 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
 120 An example
 121 ==========
 122
 123 To access hsmp device from a C program.
 124 First, you need to include the headers::
 125
 126   #include <linux/amd_hsmp.h>
 127
 128 Which defines the supported messages/message IDs.
 129
 130 Next 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
 140 The 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
 153 The ioctl would return a non-zero on failure; you can read errno to see
 154 what happened. The transaction returns 0 on success.
 155
 156 More 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
 158 eg: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip
 159
 160 User space C-APIs are made available by linking against the esmi library,
 161 which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html.
 162 See: https://github.com/amd/esmi_ib_library