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