Commit 4d95514d authored by Akshay Gupta's avatar Akshay Gupta Committed by Greg Kroah-Hartman
Browse files

misc: amd-sbi: Add document for AMD SB IOCTL description 

- This document provides AMD side band IOCTL description defined
  for APML and its usage.
  Multiple AMD custom protocols defined for side band system
  management uses this IOCTL.
  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]

Reviewed-by: default avatarNaveen Krishna Chatradhi <naveenkrishna.chatradhi@amd.com>
Signed-off-by: default avatarAkshay Gupta <akshay.gupta@amd.com>
Link: https://lore.kernel.org/r/20250428063034.2145566-11-akshay.gupta@amd.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent cf141287

Documentation/misc-devices/amd-sbi.rst

0 → 100644
+99 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=======================

AMD SIDE BAND interface

=======================



Some AMD Zen based processors supports system management

functionality via side-band interface (SBI) called

Advanced Platform Management Link (APML). APML is an I2C/I3C

based 2-wire processor target interface. APML is used to

communicate with the Remote Management Interface

(SB Remote Management Interface (SB-RMI)

and SB Temperature Sensor Interface (SB-TSI)).



More details on the interface can be found in chapter

"5 Advanced Platform Management Link (APML)" of the family/model PPR [1]_.



.. [1] https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55898_B1_pub_0_50.zip





SBRMI device

============



apml_sbrmi driver under the drivers/misc/amd-sbi creates miscdevice

/dev/sbrmi-* to let user space programs run APML mailbox, CPUID,

MCAMSR and register xfer commands.



Register sets is common across APML protocols. IOCTL is providing synchronization

among protocols as transactions may create race condition.



$ ls -al /dev/sbrmi-3c

crw-------    1 root     root       10,  53 Jul 10 11:13 /dev/sbrmi-3c



apml_sbrmi driver registers hwmon sensors for monitoring power_cap_max,

current power consumption and managing power_cap.



Characteristics of the dev node:

 * Differnet xfer protocols are defined:

	* Mailbox

	* CPUID

	* MCA_MSR

	* Register xfer



Access restrictions:

 * Only root user is allowed to open the file.

 * APML Mailbox messages and Register xfer access are read-write,

 * CPUID and MCA_MSR access is read-only.



Driver IOCTLs

=============



.. c:macro:: SBRMI_IOCTL_MBOX_CMD

.. kernel-doc:: include/uapi/misc/amd-apml.h

   :doc: SBRMI_IOCTL_MBOX_CMD

.. c:macro:: SBRMI_IOCTL_CPUID_CMD

.. kernel-doc:: include/uapi/misc/amd-apml.h

   :doc: SBRMI_IOCTL_CPUID_CMD

.. c:macro:: SBRMI_IOCTL_MCAMSR_CMD

.. kernel-doc:: include/uapi/misc/amd-apml.h

   :doc: SBRMI_IOCTL_MCAMSR_CMD

.. c:macro:: SBRMI_IOCTL_REG_XFER_CMD

.. kernel-doc:: include/uapi/misc/amd-apml.h

   :doc: SBRMI_IOCTL_REG_XFER_CMD



User-space usage

================



To access side band interface from a C program.

First, user need to include the headers::



  #include <uapi/misc/amd-apml.h>



Which defines the supported IOCTL and data structure to be passed

from the user space.



Next thing, open the device file, as follows::



  int file;



  file = open("/dev/sbrmi-*", O_RDWR);

  if (file < 0) {

    /* ERROR HANDLING */

    exit(1);

  }



The following IOCTLs are defined:



``#define SB_BASE_IOCTL_NR      	0xF9``

``#define SBRMI_IOCTL_MBOX_CMD		_IOWR(SB_BASE_IOCTL_NR, 0, struct apml_mbox_msg)``

``#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)``





User space C-APIs are made available by esmi_oob_library, hosted at

[2]_ which is provided by the E-SMS project [3]_.



.. [2] https://github.com/amd/esmi_oob_library

.. [3] https://www.amd.com/en/developer/e-sms.html