AMD Side Band Interface

AMD Side Band Interface

일부 AMD Zen 기반 processor는 APML(Advanced Platform Management Link)이라는 side-band interface(SBI)로 system management 기능을 제공합니다. APML은 I2C/I3C 기반의 2-wire processor target interface입니다.

APML은 SB-RMI(SB Remote Management Interface)와 SB-TSI(SB Temperature Sensor Interface)를 포함하는 Remote Management Interface와 통신할 때 사용합니다.

Interface 세부 정보는 해당 family/model PPR의 `5 Advanced Platform Management Link (APML)` 장과 원문에 제시된 AMD programmer-reference archive에서 확인할 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

=======================
AMD SIDE BAND interface
=======================

Some AMD Zen based processors supports system management
functionality via side-band interface (SBI) called
Advanced Platform Management Link (APML). APML is an I2C/I3C
based 2-wire processor target interface. APML is used to
communicate with the Remote Management Interface
(SB Remote Management Interface (SB-RMI)
and SB Temperature Sensor Interface (SB-TSI)).

More details on the interface can be found in chapter
"5 Advanced Platform Management Link (APML)" of the family/model PPR [1]_.

.. [1] https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip

SBRMI device

`drivers/misc/amd-sbi`의 `apml_sbrmi` driver는 user-space program이 APML mailbox, CPUID, MCAMSR, register-transfer command를 실행할 수 있도록 `/dev/sbrmi-*` miscdevice를 만듭니다.

APML protocol들이 register set을 공유하므로 transaction 사이에 race가 생기지 않도록 IOCTL이 protocol 간 synchronization을 제공합니다.

$ ls -al /dev/sbrmi-3c
crw-------    1 root     root       10,  53 Jul 10 11:13 /dev/sbrmi-3c

`apml_sbrmi` driver는 `power_cap_max`와 현재 power consumption을 monitoring하고 `power_cap`을 관리하는 hwmon sensor도 등록합니다.

• 지원하는 transfer protocol은 Mailbox, CPUID, MCA_MSR, Register xfer입니다.
• Device file은 root user만 열 수 있습니다.
• APML Mailbox message와 Register xfer는 read-write입니다.
• CPUID와 MCA_MSR 접근은 read-only입니다.

SBRMI device
============

apml_sbrmi driver under the drivers/misc/amd-sbi creates miscdevice
/dev/sbrmi-* to let user space programs run APML mailbox, CPUID,
MCAMSR and register xfer commands.

Register sets is common across APML protocols. IOCTL is providing synchronization
among protocols as transactions may create race condition.

$ ls -al /dev/sbrmi-3c
crw-------    1 root     root       10,  53 Jul 10 11:13 /dev/sbrmi-3c

apml_sbrmi driver registers hwmon sensors for monitoring power_cap_max,
current power consumption and managing power_cap.

Characteristics of the dev node:
 * Differnet xfer protocols are defined:
        * Mailbox
        * CPUID
        * MCA_MSR
        * Register xfer

Access restrictions:
 * Only root user is allowed to open the file.
 * APML Mailbox messages and Register xfer access are read-write,
 * CPUID and MCA_MSR access is read-only.

Driver IOCTL

UAPI header `include/uapi/misc/amd-apml.h`는 다음 네 IOCTL macro와 각 command의 kernel-doc을 제공합니다.

• `SBRMI_IOCTL_MBOX_CMD`
• `SBRMI_IOCTL_CPUID_CMD`
• `SBRMI_IOCTL_MCAMSR_CMD`
• `SBRMI_IOCTL_REG_XFER_CMD`

Driver IOCTLs
=============

.. c:macro:: SBRMI_IOCTL_MBOX_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
   :doc: SBRMI_IOCTL_MBOX_CMD
.. c:macro:: SBRMI_IOCTL_CPUID_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
   :doc: SBRMI_IOCTL_CPUID_CMD
.. c:macro:: SBRMI_IOCTL_MCAMSR_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
   :doc: SBRMI_IOCTL_MCAMSR_CMD
.. c:macro:: SBRMI_IOCTL_REG_XFER_CMD
.. kernel-doc:: include/uapi/misc/amd-apml.h
   :doc: SBRMI_IOCTL_REG_XFER_CMD

User-space 사용법

C program에서 side-band interface에 접근하려면 먼저 지원 IOCTL과 user-space에서 전달할 data structure를 정의하는 UAPI header를 포함합니다.

#include <uapi/misc/amd-apml.h>

그다음 device file을 read-write mode로 열고 실패를 처리합니다.

int file;

file = open("/dev/sbrmi-*", O_RDWR);
if (file < 0) {
  /* ERROR HANDLING */
  exit(1);
}

모든 command는 base IOCTL number `0xF9`와 `_IOWR`를 사용합니다. User-space C API는 E-SMS project가 제공하는 `esmi_oob_library`에서 사용할 수 있으며 원문의 두 reference URL을 따릅니다.

User-space usage
================

To access side band interface from a C program.
First, user need to include the headers::

  #include <uapi/misc/amd-apml.h>

Which defines the supported IOCTL and data structure to be passed
from the user space.

Next thing, open the device file, as follows::

  int file;

  file = open("/dev/sbrmi-*", O_RDWR);
  if (file < 0) {
    /* ERROR HANDLING */
    exit(1);
  }

The following IOCTLs are defined:

``#define SB_BASE_IOCTL_NR              0xF9``
``#define SBRMI_IOCTL_MBOX_CMD                _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_mbox_msg)``
``#define SBRMI_IOCTL_CPUID_CMD                _IOWR(SB_BASE_IOCTL_NR, 1, struct apml_cpuid_msg)``
``#define SBRMI_IOCTL_MCAMSR_CMD        _IOWR(SB_BASE_IOCTL_NR, 2, struct apml_mcamsr_msg)``
``#define SBRMI_IOCTL_REG_XFER_CMD        _IOWR(SB_BASE_IOCTL_NR, 3, struct apml_reg_xfer_msg)``


User space C-APIs are made available by esmi_oob_library, hosted at
[2]_ which is provided by the E-SMS project [3]_.

.. [2] https://github.com/amd/esmi_oob_library
.. [3] https://www.amd.com/en/developer/e-sms.html