diff mbox series

[v3,8/8] misc: amd-sbi: Add document for AMD SB IOCTL description

Message ID 20240814095954.2359863-9-akshay.gupta@amd.com (mailing list archive)
State Handled Elsewhere
Headers show
Series misc: Add AMD side band interface(SBI) functionality | expand

Commit Message

Gupta, Akshay Aug. 14, 2024, 9:59 a.m. UTC 
- 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@amd.com>
Reviewed-by: Naveen Krishna Chatradhi <naveenkrishna.chatradhi@amd.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

Comments

Greg KH Aug. 14, 2024, 10:33 a.m. UTC | #1 
On Wed, Aug 14, 2024 at 09:59:53AM +0000, Akshay Gupta wrote:
> +The following IOCTL is defined:
> +
> +``#define SB_BASE_IOCTL_NR      0xF9``
> +``#define SBRMI_IOCTL_CMD          _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_message)``

You only have 1 ioctl, so why are you saying that you are reserving
0-1F?


> +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));

This does not need to be here, pull it directly from the .h file using
kernel doc formatting please.

> +The ioctl would return a non-zero on failure; user can read errno to see
> +what happened.

That's not how the ioctl syscall works :(

> 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

What is this last line for?

thanks,

greg k-h
Gupta, Akshay Aug. 19, 2024, 10:15 a.m. UTC | #2 
On 8/14/2024 4:03 PM, Greg KH wrote:
> Caution: This message originated from an External Source. Use proper caution when opening attachments, clicking links, or responding.
>
>
> On Wed, Aug 14, 2024 at 09:59:53AM +0000, Akshay Gupta wrote:
>> +The following IOCTL is defined:
>> +
>> +``#define SB_BASE_IOCTL_NR      0xF9``
>> +``#define SBRMI_IOCTL_CMD          _IOWR(SB_BASE_IOCTL_NR, 0, struct apml_message)``
> You only have 1 ioctl, so why are you saying that you are reserving
> 0-1F?
>
Currently we have only 1 IOCTL, but will add IOCTL for SBTSI.

I have reserved considering the future use cases.

However, we may not need up to 1F will restrict it to 0-Fh

>> +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));
> This does not need to be here, pull it directly from the .h file using
> kernel doc formatting please.
I will update this.
>> +The ioctl would return a non-zero on failure; user can read errno to see
>> +what happened.
> That's not how the ioctl syscall works :(
I will document the errors returned in the header file.
>> 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 projecthttps://www.amd.com/en/developer/e-sms.html.
>> +Link:https://github.com/amd/esmi_oob_library
> What is this last line for?
I will rewrite the statement as follows:

User space C-APIs are made available by esmi_oob_library hosted athttps://github.com/amd/esmi_oob_library
which is provided as part of E-SMS projecthttps://www.amd.com/en/developer/e-sms.html.

I will wait for feedback on other patches before submitting next version.
> thanks,
>
> greg k-h
>
diff mbox series

Patch

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