From: Prathima - Document AMD sideband IOCTL description defined for SBTSI and its usage. User space C-APIs are made available by esmi_oob_library [1], which is provided by the E-SMS project [2]. Link: https://github.com/amd/esmi_oob_library [1] Link: https://www.amd.com/en/developer/e-sms.html [2] Include a user-space open example for /dev/sbtsi-* and list auxiliary bus sysfs paths. Reviewed-by: Akshay Gupta Signed-off-by: Prathima --- Changes since v3: - Address maintainer's comment by changing "xfer" to "transfer" - Revise the document to clarify the client address for I2C and the assigned address for I3C Changes since v2: - Update misc node names info as per socket Changes since v1: - Elaborate the document Documentation/misc-devices/amd-sbi.rst | 74 ++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/Documentation/misc-devices/amd-sbi.rst b/Documentation/misc-devices/amd-sbi.rst index f91ddadefe48..648d743903b7 100644 --- a/Documentation/misc-devices/amd-sbi.rst +++ b/Documentation/misc-devices/amd-sbi.rst @@ -48,6 +48,66 @@ Access restrictions: * APML Mailbox messages and Register xfer access are read-write, * CPUID and MCA_MSR access is read-only. +SBTSI device +============ + +sbtsi driver under the drivers/misc/amd-sbi creates miscdevice +/dev/sbtsi-* to let user space programs run APML TSI register transfer +commands. + +The driver supports both I2C and I3C transports for SB-TSI targets. +The transport is selected by the bus where the device is enumerated. + +Misc device: + * In 1P socket 0: /dev/sbtsi-4c + * In 2P socket 0: /dev/sbtsi-4c, socket 1: /dev/sbtsi-48 + +.. code-block:: bash + + $ ls -al /dev/sbtsi-4c + crw------- 1 root root 10, 116 Apr 2 05:22 /dev/sbtsi-4c + + +Access restrictions: + * Only root user is allowed to open the file. + * APML TSI Register transfer access is read-write. + +SBTSI hwmon interface +===================== + +The sbtsi_temp auxiliary driver binds to the auxiliary device published +by the core sbtsi driver on the auxiliary bus. The auxiliary device is +named amd-sbtsi.temp-sensor., where is the device's transfer +address: the client address for I2C, or the assigned-address for I3C. + +Note that the auxiliary bus formats in decimal, whereas the +/dev/sbtsi-* misc node formats its address in hex. The two therefore +differ for the same device: an I2C/I3C sensor at address 0x4c appears as the +misc node /dev/sbtsi-4c and the auxiliary device +amd-sbtsi.temp-sensor.76. + +It registers a hwmon device, providing a standard Linux hwmon interface +for reading CPU temperature and managing temperature limits. + +The hwmon device appears under ``/sys/class/hwmon/`` when both ``sbtsi.ko`` +and ``sbtsi_temp.ko`` are loaded. + +Verify auxiliary bus device:: + + ls /sys/bus/auxiliary/devices/ + # e.g. amd-sbtsi.temp-sensor.76 for an I2C/I3C sensor at address 0x4c + +Example usage:: + + # Read current temperature + cat /sys/class/hwmon/hwmon/temp1_input + + # Set high temperature limit to 70 °C + echo 70000 > /sys/class/hwmon/hwmon/temp1_max + + # Verify + cat /sys/class/hwmon/hwmon/temp1_max + Driver IOCTLs ============= @@ -63,6 +123,9 @@ Driver IOCTLs .. c:macro:: SBRMI_IOCTL_REG_XFER_CMD .. kernel-doc:: include/uapi/misc/amd-apml.h :doc: SBRMI_IOCTL_REG_XFER_CMD +.. c:macro:: SBTSI_IOCTL_REG_XFER_CMD +.. kernel-doc:: include/uapi/misc/amd-apml.h + :doc: SBTSI_IOCTL_REG_XFER_CMD User-space usage ================ @@ -85,6 +148,16 @@ Next thing, open the device file, as follows:: exit(1); } +To open SB-TSI device:: + + int file; + + file = open("/dev/sbtsi-4c", O_RDWR); + if (file < 0) { + /* ERROR HANDLING */ + exit(1); + } + The following IOCTLs are defined: ``#define SB_BASE_IOCTL_NR 0xF9`` @@ -92,6 +165,7 @@ The following IOCTLs are defined: ``#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)`` +``#define SBTSI_IOCTL_REG_XFER_CMD _IOWR(SB_BASE_IOCTL_NR, 4, struct apml_tsi_xfer_msg)`` User space C-APIs are made available by esmi_oob_library, hosted at -- 2.34.1