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://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip 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 102