AMD HSMP Interface

AMD HSMP interface 개요

이 문서는 `GPL-2.0`으로 배포됩니다. AMD의 newer Fam19h(model `0x00-0x1f`, `0x30-0x3f`, `0x90-0x9f`, `0xa0-0xaf`) 및 Fam1Ah(model `0x00-0x1f`) EPYC server processor는 HSMP(Host System Management Port)를 통해 system-management 기능을 지원합니다.

HSMP는 mailbox register 집합을 통해 OS-level software가 system-management function에 접근하도록 제공하는 interface입니다.

interface의 자세한 내용은 해당 family/model PPR의 chapter `7 Host System Management Port (HSMP)`에 있습니다. 예시 문서는 `https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip`입니다.

HSMP interface는 EPYC server CPU 제품군과 MI300A APU에서 지원됩니다.

driver module과 /dev/hsmp 접근 정책

`drivers/platforms/x86/amd/hsmp/` 아래의 `amd_hsmp` driver는 ACPI object 기반 probing, platform-device 기반 probing, 두 driver가 공유하는 common code를 각각 별도 file로 구현합니다.

앞의 두 config 중 하나를 선택하면 `CONFIG_AMD_HSMP`가 자동으로 선택됩니다. ACPI driver와 plat driver는 모두 userspace program이 HSMP mailbox command를 실행할 수 있도록 miscdevice `/dev/hsmp`를 만듭니다.

$ ls -al /dev/hsmp
crw-r--r-- 1 root root 10, 123 Jan 21 21:41 /dev/hsmp

device node의 access mode별 용도는 다음과 같습니다.

• write mode는 set/configure command 실행에 사용합니다.
• read mode는 get/status-monitor command 실행에 사용합니다.

접근 권한은 다음과 같이 제한됩니다.

• root user만 file을 write mode로 열 수 있습니다.
• 모든 user가 file을 read mode로 열 수 있습니다.

kernel 내부 integration은 다음 transport 규칙을 따릅니다.

• 다른 kernel subsystem은 export된 `hsmp_send_message()` function을 사용할 수 있습니다.
• caller 사이의 locking은 driver가 처리합니다.

metrics table binary sysfs

AMD MI300A MCM은 SMU의 system-management information 대부분을 한 번에 가져오는 `GET_METRICS_TABLE` message를 제공합니다.

metrics table은 socket별 sysfs directory 아래의 hexadecimal binary file `/sys/devices/platform/amd_hsmp/socket%d/metrics_bin`으로 노출됩니다.

metrics table 정의는 public PPR의 일부로 문서화될 예정이며 같은 정의가 `amd_hsmp.h` header에도 있습니다.

HSMP telemetry sysfs file

다음 telemetry sysfs file은 `/sys/devices/platform/AMDI0097:0X/`에 제공됩니다.

ACPI device object format

socket ID가 `ID00`일 때 `amd_hsmp` driver가 기대하는 ACPI object format은 다음과 같습니다.

Device(HSMP)
              {
                      Name(_HID, "AMDI0097")
                      Name(_UID, "ID00")
                      Name(HSE0, 0x00000001)
                      Name(RBF0, ResourceTemplate()
                      {
                              Memory32Fixed(ReadWrite, 0xxxxxxx, 0x00100000)
                      })
                      Method(_CRS, 0, NotSerialized)
                      {
                              Return(RBF0)
                      }
                      Method(_STA, 0, NotSerialized)
                      {
                              If(LEqual(HSE0, One))
                              {
                                      Return(0x0F)
                              }
                              Else
                              {
                                      Return(Zero)
                              }
                      }
                      Name(_DSD, Package(2)
                      {
                              Buffer(0x10)
                              {
                                      0x9D, 0x61, 0x4D, 0xB7, 0x07, 0x57, 0xBD, 0x48,
                                      0xA6, 0x9F, 0x4E, 0xA2, 0x87, 0x1F, 0xC2, 0xF6
                              },
                              Package(3)
                              {
                                      Package(2) {"MsgIdOffset", 0x00010934},
                                      Package(2) {"MsgRspOffset", 0x00010980},
                                      Package(2) {"MsgArgOffset", 0x000109E0}
                              }
                      })
              }

HSMP HWMON power sensor

HSMP power sensor는 hwmon interface에 등록됩니다. socket마다 별도 hwmon directory가 생성되고 다음 file이 만들어집니다.

C program에서 device 열기

C program에서 HSMP device에 접근하려면 먼저 지원 message와 message ID를 정의하는 `<linux/amd_hsmp.h>` header를 include합니다.

#include <linux/amd_hsmp.h>

그다음 `/dev/hsmp`를 `O_RDWR`로 엽니다. 실패하면 `errno`로 원인을 확인하고 적절히 error handling합니다.

int file;

file = open("/dev/hsmp", O_RDWR);
if (file < 0) {
  /* ERROR HANDLING; you can check errno to see what went wrong */
  exit(1);
}

HSMP_IOCTL_CMD와 hsmp_message

정의된 ioctl 형식은 `ioctl(file, HSMP_IOCTL_CMD, struct hsmp_message *msg)`입니다. 마지막 argument는 다음 `struct hsmp_message`를 가리키는 pointer입니다.

struct hsmp_message {
        __u32        msg_id;                                /* Message ID */
        __u16        num_args;                        /* Number of input argument words in message */
        __u16        response_sz;                        /* Number of expected output/response words */
        __u32        args[HSMP_MAX_MSG_LEN];                /* argument/response buffer */
        __u16        sock_ind;                        /* socket number */
};

`msg_id`는 message ID, `num_args`는 input argument word 수, `response_sz`는 예상 output/response word 수입니다. `args[HSMP_MAX_MSG_LEN]`은 argument와 response가 공유하는 buffer이고 `sock_ind`는 socket number입니다.

ioctl은 실패하면 non-zero를 반환하며 `errno`에서 원인을 읽을 수 있습니다. transaction이 성공하면 0을 반환합니다.

PPR과 userspace library

interface와 message 정의의 자세한 내용은 해당 family/model PPR의 chapter `7 Host System Management Port (HSMP)`를 참조합니다. 예시는 `https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip`입니다.

userspace C API는 E-SMS project가 제공하는 esmi library를 link해 사용할 수 있습니다. project는 `https://www.amd.com/en/developer/e-sms.html`, library source는 `https://github.com/amd/esmi_ib_library`에서 확인할 수 있습니다.