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 51SBTSI device 52============ 53 54sbtsi driver under the drivers/misc/amd-sbi creates miscdevice 55/dev/sbtsi-* to let user space programs run APML TSI register transfer 56commands. 57 58The driver supports both I2C and I3C transports for SB-TSI targets. 59The transport is selected by the bus where the device is enumerated. 60 61Misc device: 62 * In 1P socket 0: /dev/sbtsi-4c 63 * In 2P socket 0: /dev/sbtsi-4c, socket 1: /dev/sbtsi-48 64 65.. code-block:: bash 66 67 $ ls -al /dev/sbtsi-4c 68 crw------- 1 root root 10, 116 Apr 2 05:22 /dev/sbtsi-4c 69 70 71Access restrictions: 72 * Only root user is allowed to open the file. 73 * APML TSI Register transfer access is read-write. 74 75SBTSI hwmon interface 76===================== 77 78The sbtsi_temp auxiliary driver binds to the auxiliary device published 79by the core sbtsi driver on the auxiliary bus. The auxiliary device is 80named amd-sbtsi.temp-sensor.<id>, where <id> is the device's transfer 81address: the client address for I2C, or the assigned-address for I3C. 82 83Note that the auxiliary bus formats <id> in decimal, whereas the 84/dev/sbtsi-* misc node formats its address in hex. The two therefore 85differ for the same device: an I2C/I3C sensor at address 0x4c appears as the 86misc node /dev/sbtsi-4c and the auxiliary device 87amd-sbtsi.temp-sensor.76. 88 89It registers a hwmon device, providing a standard Linux hwmon interface 90for reading CPU temperature and managing temperature limits. 91 92The hwmon device appears under ``/sys/class/hwmon/`` when both ``sbtsi.ko`` 93and ``sbtsi_temp.ko`` are loaded. 94 95Verify auxiliary bus device:: 96 97 ls /sys/bus/auxiliary/devices/ 98 # e.g. amd-sbtsi.temp-sensor.76 for an I2C/I3C sensor at address 0x4c 99 100Example usage:: 101 102 # Read current temperature 103 cat /sys/class/hwmon/hwmon<N>/temp1_input 104 105 # Set high temperature limit to 70 °C 106 echo 70000 > /sys/class/hwmon/hwmon<N>/temp1_max 107 108 # Verify 109 cat /sys/class/hwmon/hwmon<N>/temp1_max 110 111Driver IOCTLs 112============= 113 114.. c:macro:: SBRMI_IOCTL_MBOX_CMD 115.. kernel-doc:: include/uapi/misc/amd-apml.h 116 :doc: SBRMI_IOCTL_MBOX_CMD 117.. c:macro:: SBRMI_IOCTL_CPUID_CMD 118.. kernel-doc:: include/uapi/misc/amd-apml.h 119 :doc: SBRMI_IOCTL_CPUID_CMD 120.. c:macro:: SBRMI_IOCTL_MCAMSR_CMD 121.. kernel-doc:: include/uapi/misc/amd-apml.h 122 :doc: SBRMI_IOCTL_MCAMSR_CMD 123.. c:macro:: SBRMI_IOCTL_REG_XFER_CMD 124.. kernel-doc:: include/uapi/misc/amd-apml.h 125 :doc: SBRMI_IOCTL_REG_XFER_CMD 126.. c:macro:: SBTSI_IOCTL_REG_XFER_CMD 127.. kernel-doc:: include/uapi/misc/amd-apml.h 128 :doc: SBTSI_IOCTL_REG_XFER_CMD 129 130User-space usage 131================ 132 133To access side band interface from a C program. 134First, user need to include the headers:: 135 136 #include <uapi/misc/amd-apml.h> 137 138Which defines the supported IOCTL and data structure to be passed 139from the user space. 140 141Next thing, open the device file, as follows:: 142 143 int file; 144 145 file = open("/dev/sbrmi-*", O_RDWR); 146 if (file < 0) { 147 /* ERROR HANDLING */ 148 exit(1); 149 } 150 151To open SB-TSI device:: 152 153 int file; 154 155 file = open("/dev/sbtsi-4c", O_RDWR); 156 if (file < 0) { 157 /* ERROR HANDLING */ 158 exit(1); 159 } 160 161The following IOCTLs are defined: 162 163``#define SB_BASE_IOCTL_NR 0xF9`` 164``#define SBRMI_IOCTL_MBOX_CMD _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_mbox_msg)`` 165``#define SBRMI_IOCTL_CPUID_CMD _IOWR(SB_BASE_IOCTL_NR, 1, struct apml_cpuid_msg)`` 166``#define SBRMI_IOCTL_MCAMSR_CMD _IOWR(SB_BASE_IOCTL_NR, 2, struct apml_mcamsr_msg)`` 167``#define SBRMI_IOCTL_REG_XFER_CMD _IOWR(SB_BASE_IOCTL_NR, 3, struct apml_reg_xfer_msg)`` 168``#define SBTSI_IOCTL_REG_XFER_CMD _IOWR(SB_BASE_IOCTL_NR, 4, struct apml_tsi_xfer_msg)`` 169 170 171User space C-APIs are made available by esmi_oob_library, hosted at 172[2]_ which is provided by the E-SMS project [3]_. 173 174.. [2] https://github.com/amd/esmi_oob_library 175.. [3] https://www.amd.com/en/developer/e-sms.html 176