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

From: Akshay Gupta

Date: Wed Nov 11 2026 - 00:42:05 EST


From: Prathima Lk <Prathima.Lk@xxxxxxx>

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@xxxxxxx>
Signed-off-by: Akshay Gupta <Akshay.Gupta@xxxxxxx>
---
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