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$ ls -al /dev/sbrmi-3c 32crw------- 1 root root 10, 53 Jul 10 11:13 /dev/sbrmi-3c 33 34apml_sbrmi driver registers hwmon sensors for monitoring power_cap_max, 35current power consumption and managing power_cap. 36 37Characteristics of the dev node: 38 * Differnet xfer protocols are defined: 39 * Mailbox 40 * CPUID 41 * MCA_MSR 42 * Register xfer 43 44Access restrictions: 45 * Only root user is allowed to open the file. 46 * APML Mailbox messages and Register xfer access are read-write, 47 * CPUID and MCA_MSR access is read-only. 48 49Driver IOCTLs 50============= 51 52.. c:macro:: SBRMI_IOCTL_MBOX_CMD 53.. kernel-doc:: include/uapi/misc/amd-apml.h 54 :doc: SBRMI_IOCTL_MBOX_CMD 55.. c:macro:: SBRMI_IOCTL_CPUID_CMD 56.. kernel-doc:: include/uapi/misc/amd-apml.h 57 :doc: SBRMI_IOCTL_CPUID_CMD 58.. c:macro:: SBRMI_IOCTL_MCAMSR_CMD 59.. kernel-doc:: include/uapi/misc/amd-apml.h 60 :doc: SBRMI_IOCTL_MCAMSR_CMD 61.. c:macro:: SBRMI_IOCTL_REG_XFER_CMD 62.. kernel-doc:: include/uapi/misc/amd-apml.h 63 :doc: SBRMI_IOCTL_REG_XFER_CMD 64 65User-space usage 66================ 67 68To access side band interface from a C program. 69First, user need to include the headers:: 70 71 #include <uapi/misc/amd-apml.h> 72 73Which defines the supported IOCTL and data structure to be passed 74from the user space. 75 76Next thing, open the device file, as follows:: 77 78 int file; 79 80 file = open("/dev/sbrmi-*", O_RDWR); 81 if (file < 0) { 82 /* ERROR HANDLING */ 83 exit(1); 84 } 85 86The following IOCTLs are defined: 87 88``#define SB_BASE_IOCTL_NR 0xF9`` 89``#define SBRMI_IOCTL_MBOX_CMD _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_mbox_msg)`` 90``#define SBRMI_IOCTL_CPUID_CMD _IOWR(SB_BASE_IOCTL_NR, 1, struct apml_cpuid_msg)`` 91``#define SBRMI_IOCTL_MCAMSR_CMD _IOWR(SB_BASE_IOCTL_NR, 2, struct apml_mcamsr_msg)`` 92``#define SBRMI_IOCTL_REG_XFER_CMD _IOWR(SB_BASE_IOCTL_NR, 3, struct apml_reg_xfer_msg)`` 93 94 95User space C-APIs are made available by esmi_oob_library, hosted at 96[2]_ which is provided by the E-SMS project [3]_. 97 98.. [2] https://github.com/amd/esmi_oob_library 99.. [3] https://www.amd.com/en/developer/e-sms.html 100