[PATCH v1 3/3] docs: amd-sbi: document TBAI trace-buffer ioctl

[Akshay Gupta <Akshay.Gupta@amd.com>]

From: Prathima Lk <Prathima.Lk@amd.com>

This change documents the SB-TSI Trace Buffer Acquire Interface (TBAI)
in the amd-sbi guide. It adds a prose section describing the shared
/dev/sbtsi-* node, the I3C-only requirement, the acquire and flush
operations, their return codes, and the serialization with register
access under the device lock.
It also adds the SBTBAI_IOCTL_CMD kernel-doc reference under Driver
IOCTLs and lists the ioctl define in the user-space usage list.
The documentation build was run locally to confirm the new section
and kernel-doc references render without warnings or errors.

Signed-off-by: Prathima Lk <Prathima.Lk@amd.com>
Signed-off-by: Akshay Gupta <Akshay.Gupta@amd.com>
---
 Documentation/misc-devices/amd-sbi.rst | 60 +++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/Documentation/misc-devices/amd-sbi.rst b/Documentation/misc-devices/amd-sbi.rst
index 648d743903b7..9cf7c003d00c 100644
--- a/Documentation/misc-devices/amd-sbi.rst
+++ b/Documentation/misc-devices/amd-sbi.rst
@@ -53,7 +53,7 @@ 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.
+and, on I3C targets, TBAI trace-buffer 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.
@@ -68,10 +68,64 @@ Misc device:
    crw-------    1 root     root       10, 116 Apr  2 05:22 /dev/sbtsi-4c
 
 
+Characteristics of the dev node:
+ * Different xfer protocols are defined:
+     * TSI register xfer (SBTSI_IOCTL_REG_XFER_CMD)
+     * TBAI trace-buffer access (SBTBAI_IOCTL_CMD), I3C only
+ * Requests from both ioctls are serialized under the same device lock.
+
 Access restrictions:
  * Only root user is allowed to open the file.
  * APML TSI Register transfer access is read-write.
 
+Trace Buffer Acquire Interface (TBAI)
+===========================================
+
+Trace Buffer Acquire Interface (TBAI) is defined in the Thermal
+Management (THM) block for the BMC(external controller) to access the
+Microprocessor's (MP) trace data, and the interface abstracts away the
+Trace buffer target address space for the trace buffer destination.
+
+Trace buffer target (TBT) refers to the on-die destination of a trace
+buffer entry.
+
+The Distributed Trace Buffer feature is to have a common debug tracing
+solution for all MPs, that is natively visible to the BMC (APML/MCTP).
+Each MP (bootcode and off-chip FW) puts trace logs into its local buffer
+and provides an interface called Debug Trace Buffer Acquire
+Interface using SB-TSI registers for the BMC to fetch the debug
+trace data through the THM out of band (OOB) I3C.
+
+TBAI is accessed with SBTBAI_IOCTL_CMD on the same /dev/sbtsi-* node
+as SBTSI_IOCTL_REG_XFER_CMD. It is only supported when the SB-TSI
+target is attached over I3C; on I2C the ioctl returns -EOPNOTSUPP.
+TBAI requests and TSI register transfers share the device lock, so
+they never interleave on the bus.
+
+Two operations are supported, selected by the command byte in the request:
+ * Trace Buffer Acquire (0x31): read 1 to 32 DWORDs of trace data from a
+   given look-up-table (LUT) index and entry offset.
+ * Trace Buffer Flush (0x32): reset the TBAI internal logic when the trace
+   buffer target does not respond. The 32-bit flush status (0xDEADBEEF)
+   is returned in the first DWORD of data_out, low byte first;
+   fw_ret_code is 0.
+
+The ioctl returns:
+ * 0: the request completed. All requested DWORDs are valid in the
+   fixed data_out array of struct apml_tbai_msg.
+ * -EPROTOTYPE: the trace buffer target reported an error. fw_ret_code
+   holds the AMD_SBI_TBAI_TBT_ERR* code and data_out is zeroed.
+ * -EMSGSIZE: the device returned less data than requested. Nothing is
+   copied back to the message.
+ * -EOPNOTSUPP: if the SB-TSI device is attached over I2C.
+
+After -EPROTOTYPE or -EMSGSIZE, issue a Trace Buffer Flush before
+retrying the acquire.
+
+reg_in[4] is the actual number of DWORDs to read, from 1 to
+AMD_SBI_MAX_TBAI_DWORDS. The driver handles the hardware encoding and
+splits requests larger than 8 DWORDs into multiple transactions.
+
 SBTSI hwmon interface
 =====================
 
@@ -126,6 +180,9 @@ Driver IOCTLs
 .. c:macro:: SBTSI_IOCTL_REG_XFER_CMD
 .. kernel-doc:: include/uapi/misc/amd-apml.h
    :doc: SBTSI_IOCTL_REG_XFER_CMD
+.. c:macro:: SBTBAI_IOCTL_CMD
+.. kernel-doc:: include/uapi/misc/amd-apml.h
+   :doc: SBTBAI_IOCTL_CMD
 
 User-space usage
 ================
@@ -166,6 +223,7 @@ The following IOCTLs are defined:
 ``#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)``
+``#define SBTBAI_IOCTL_CMD             _IOWR(SB_BASE_IOCTL_NR, 5, struct apml_tbai_msg)``
 
 
 User space C-APIs are made available by esmi_oob_library, hosted at
-- 
2.34.1