[PATCH v8 13/17] firmware: arm_scmi: Add debugfs ABI documentation for Raw mode

Cristian Marussi
2023-01-18T12:22:12Z

Add description of the debugfs SCMI Raw ABI.

Signed-off-by: Cristian Marussi <cristian.marussi@arm.com>
---
v5 --> v6
- split debugfs Raw ABI doc into its own docfile and changed
the top rootfs structure
v4 --> v5
- updated ABI description for multiple SCMI instances support
---
Documentation/ABI/testing/debugfs-scmi-raw | 66 ++++++++++++++++++++++
1 file changed, 66 insertions(+)
create mode 100644 Documentation/ABI/testing/debugfs-scmi-raw

diff --git a/Documentation/ABI/testing/debugfs-scmi-raw b/Documentation/ABI/testing/debugfs-scmi-raw
new file mode 100644
index 000000000000..45817d465b1f
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-scmi-raw
@@ -0,0 +1,66 @@
+What: /sys/kernel/debug/scmi/<n>/raw/message
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw synchronous message injection/snooping facility; write
+ a complete SCMI synchronous command message (header included)
+ in little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n>.
+ Any subsequently received response can be read from this same
+ entry if it arrived within the configured timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/message_async
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw asynchronous message injection/snooping facility; write
+ a complete SCMI asynchronous command message (header included)
+ in little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n>.
+ Any subsequently received response can be read from this same
+ entry if it arrived within the configured timeout.
+ Any additional delayed response received afterwards can be read
+ from this same entry too if it arrived within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/errors
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw message errors facility; any kind of timed-out or
+ generally unexpectedly received SCMI message, for instance <n>,
+ can be read from this entry.
+ Each read gives back one message at time (receiving an EOF at
+ each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/notification
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw notification snooping facility; any notification
+ emitted by the backend SCMI server, for instance <n>, can be
+ read from this entry.
+ Each read gives back one message at time (receiving an EOF at
+ each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/reset
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw stack reset facility; writing a value to this entry
+ causes the internal queues of any kind of received message,
+ still pending to be read out for instance <n>, to be immediately
+ flushed.
+ Can be used to reset and clean the SCMI Raw stack between to
+ different test-run.
+Users: Debugging, any userspace test suite