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