| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20240814095954.2359863-9-akshay.gupta@amd.com>
Date: Wed, 14 Aug 2024 09:59:53 +0000
From: Akshay Gupta <akshay.gupta@....com>
To: <linux-hwmon@...r.kernel.org>, <linux-kernel@...r.kernel.org>
CC: <linux@...ck-us.net>, <gregkh@...uxfoundation.org>, <arnd@...db.de>,
<naveenkrishna.chatradhi@....com>, Akshay Gupta <akshay.gupta@....com>
Subject: [PATCH v3 8/8] misc: amd-sbi: Add document for AMD SB IOCTL description
- This document provide 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 linking against the esmi_oob_library,
which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html.
See: https://github.com/amd/esmi_oob_library
Signed-off-by: Akshay Gupta <akshay.gupta@....com>
Reviewed-by: Naveen Krishna Chatradhi <naveenkrishna.chatradhi@....com>
---
Changes since v2:
- update the MACROS name as per feedback
Changes since v1:
- New patch
Documentation/misc-devices/amd-sbi.rst | 121 +++++++++++++++++++++++++
1 file changed, 121 insertions(+)
create mode 100644 Documentation/misc-devices/amd-sbi.rst
diff --git a/Documentation/misc-devices/amd-sbi.rst b/Documentation/misc-devices/amd-sbi.rst
new file mode 100644
index 000000000000..ff90ad50a29c
--- /dev/null
+++ b/Documentation/misc-devices/amd-sbi.rst
@@ -0,0 +1,121 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+AMD SIDE BAND interface
+=======================
+
+AMD server line of 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
+Eg: 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:
+ * message ids are defined to run differnet xfer protocols:
+ * Mailbox: 0x0 ... 0x999
+ * CPUID: 0x1000
+ * MCA_MSR: 0x1001
+ * Register xfer: 0x1002
+
+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.
+
+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; you can check errno to see what went wrong */
+ exit(1);
+ }
+
+The following IOCTL is defined:
+
+``#define SB_BASE_IOCTL_NR 0xF9``
+``#define SBRMI_IOCTL_CMD _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_message)``
+
+Data structure::
+ struct apml_message {
+ /* message ids:
+ * Mailbox Messages: 0x0 ... 0x999
+ * APML_CPUID: 0x1000
+ * APML_MCA_MSR: 0x1001
+ * APML_REG: 0x1002
+ */
+ __u32 cmd;
+ /*
+ * 8 bit data for reg read,
+ * 32 bit data in case of mailbox,
+ * up to 64 bit in case of cpuid and mca msr
+ */
+ union {
+ __u64 cpu_msr_out;
+ __u32 mb_out[2];
+ __u8 reg_out[8];
+ } data_out;
+ /*
+ * [0]...[3] mailbox 32bit input
+ * cpuid & mca msr,
+ * rmi rd/wr: reg_offset
+ * [4][5] cpuid & mca msr: thread
+ * [4] rmi reg wr: value
+ * [6] cpuid: ext function & read eax/ebx or ecx/edx
+ * [7:0] -> bits [7:4] -> ext function &
+ * bit [0] read eax/ebx or ecx/edx
+ * [7] read/write functionality
+ */
+ union {
+ __u64 cpu_msr_in;
+ __u32 mb_in[2];
+ __u8 reg_in[8];
+ } data_in;
+ /*
+ * Status code is returned in case of CPUID/MCA access
+ * Error code is returned in case of soft mailbox
+ */
+ __u32 fw_ret_code;
+ } __attribute__((packed));
+
+The ioctl would return a non-zero on failure; user can read errno to see
+what happened. The transaction returns 0 on success.
+
+User space C-APIs are made available by linking against the esmi_oob_library,
+which is provided by the E-SMS project https://www.amd.com/en/developer/e-sms.html.
+Link: https://github.com/amd/esmi_oob_library
--
2.44.0
Powered by blists - more mailing lists