amd-sbi.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=======================
  4AMD SIDE BAND interface
  5=======================
  6
  7Some AMD Zen based processors supports system management
  8functionality via side-band interface (SBI) called
  9Advanced Platform Management Link (APML). APML is an I2C/I3C
 10based 2-wire processor target interface. APML is used to
 11communicate with the Remote Management Interface
 12(SB Remote Management Interface (SB-RMI)
 13and SB Temperature Sensor Interface (SB-TSI)).
 14
 15More details on the interface can be found in chapter
 16"5 Advanced Platform Management Link (APML)" of the family/model PPR [1]_.
 17
 18.. [1] https://docs.amd.com/v/u/en-US/55898_B1_pub_0_50
 19
 20
 21SBRMI device
 22============
 23
 24apml_sbrmi driver under the drivers/misc/amd-sbi creates miscdevice
 25/dev/sbrmi-* to let user space programs run APML mailbox, CPUID,
 26MCAMSR and register xfer commands.
 27
 28Register sets is common across APML protocols. IOCTL is providing synchronization
 29among protocols as transactions may create race condition.
 30
 31.. code-block:: bash
 32
 33   $ ls -al /dev/sbrmi-3c
 34   crw-------    1 root     root       10,  53 Jul 10 11:13 /dev/sbrmi-3c
 35
 36apml_sbrmi driver registers hwmon sensors for monitoring power_cap_max,
 37current power consumption and managing power_cap.
 38
 39Characteristics of the dev node:
 40 * Differnet xfer protocols are defined:
 41	* Mailbox
 42	* CPUID
 43	* MCA_MSR
 44	* Register xfer
 45
 46Access restrictions:
 47 * Only root user is allowed to open the file.
 48 * APML Mailbox messages and Register xfer access are read-write,
 49 * CPUID and MCA_MSR access is read-only.
 50
 51Driver IOCTLs
 52=============
 53
 54.. c:macro:: SBRMI_IOCTL_MBOX_CMD
 55.. kernel-doc:: include/uapi/misc/amd-apml.h
 56   :doc: SBRMI_IOCTL_MBOX_CMD
 57.. c:macro:: SBRMI_IOCTL_CPUID_CMD
 58.. kernel-doc:: include/uapi/misc/amd-apml.h
 59   :doc: SBRMI_IOCTL_CPUID_CMD
 60.. c:macro:: SBRMI_IOCTL_MCAMSR_CMD
 61.. kernel-doc:: include/uapi/misc/amd-apml.h
 62   :doc: SBRMI_IOCTL_MCAMSR_CMD
 63.. c:macro:: SBRMI_IOCTL_REG_XFER_CMD
 64.. kernel-doc:: include/uapi/misc/amd-apml.h
 65   :doc: SBRMI_IOCTL_REG_XFER_CMD
 66
 67User-space usage
 68================
 69
 70To access side band interface from a C program.
 71First, user need to include the headers::
 72
 73  #include <uapi/misc/amd-apml.h>
 74
 75Which defines the supported IOCTL and data structure to be passed
 76from the user space.
 77
 78Next thing, open the device file, as follows::
 79
 80  int file;
 81
 82  file = open("/dev/sbrmi-*", O_RDWR);
 83  if (file < 0) {
 84    /* ERROR HANDLING */
 85    exit(1);
 86  }
 87
 88The following IOCTLs are defined:
 89
 90``#define SB_BASE_IOCTL_NR      	0xF9``
 91``#define SBRMI_IOCTL_MBOX_CMD		_IOWR(SB_BASE_IOCTL_NR, 0, struct apml_mbox_msg)``
 92``#define SBRMI_IOCTL_CPUID_CMD		_IOWR(SB_BASE_IOCTL_NR, 1, struct apml_cpuid_msg)``
 93``#define SBRMI_IOCTL_MCAMSR_CMD	_IOWR(SB_BASE_IOCTL_NR, 2, struct apml_mcamsr_msg)``
 94``#define SBRMI_IOCTL_REG_XFER_CMD	_IOWR(SB_BASE_IOCTL_NR, 3, struct apml_reg_xfer_msg)``
 95
 96
 97User space C-APIs are made available by esmi_oob_library, hosted at
 98[2]_ which is provided by the E-SMS project [3]_.
 99
100.. [2] https://github.com/amd/esmi_oob_library
101.. [3] https://www.amd.com/en/developer/e-sms.html