[5/7] Remoteproc: Documentation: add userspace api

Commit Message

anish kumar Oct. 22, 2024, 9:35 p.m. UTC

Add information about how userspace
can control the remoteproc framework
and different ways to do that.

Signed-off-by: anish kumar <[e-mail]>
---
 Documentation/remoteproc/index.rst          |  2 +
 Documentation/remoteproc/remoteproc-api.rst | 75 +++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 Documentation/remoteproc/remoteproc-api.rst

Patch

diff --git a/Documentation/remoteproc/index.rst b/Documentation/remoteproc/index.rst
index af3573123ee4..243b5652cf79 100644
--- a/Documentation/remoteproc/index.rst
+++ b/Documentation/remoteproc/index.rst
@@ -18,6 +18,8 @@  Authors:
    :maxdepth: 1
 
    remoteproc
+   remoteproc-kernel-api
+   remoteproc-api
 
 Mailing List
 ------------
diff --git a/Documentation/remoteproc/remoteproc-api.rst b/Documentation/remoteproc/remoteproc-api.rst
new file mode 100644
index 000000000000..548d3658fc1c
--- /dev/null
+++ b/Documentation/remoteproc/remoteproc-api.rst
@@ -0,0 +1,75 @@ 
+==================================
+The Linux Remoteproc userspace API
+==================================
+
+Introduction
+============
+
+A Remoteproc (rproc) is a subsystem for managing the lifecycle
+of a processor that is connected to Linux.
+
+At times, userspace may need to check the state of the remote processor to
+prevent other processes from using it. For instance, if the remote processor
+is a DSP used for playback, there may be situations where the DSP is
+undergoing recovery and cannot be used. In such cases, attempts to access the
+DSP for playback should be blocked. The rproc framework provides sysfs APIs
+to inform userspace of the processor's current status which should be utilised
+to achieve the same.
+
+Additionally, there are scenarios where userspace applications need to explicitly
+control the rproc. In these cases, rproc also offers the file descriptors.
+
+The simplest API
+================
+
+Below set of api's can be used to start and stop the rproc
+where 'X' refers to instance of associated remoteproc. There can be systems
+where there are more than one rprocs such as multiple DSP's
+connected to application processors running Linux.
+::
+   echo start > /sys/class/remoteproc/remoteprocX/state
+   echo stop > /sys/class/remoteproc/remoteprocX/state
+
+To know the state of rproc:
+
+.. code-block::
+
+   cat /sys/class/remoteproc/remoteprocX/state
+
+
+To dynamically replace firmware, execute the following commands:
+
+.. code-block::
+
+   echo stop > /sys/class/remoteproc/remoteprocX/state
+   echo -n <firmware_name> >
+   /sys/class/remoteproc/remoteprocX/firmware
+   echo start > /sys/class/remoteproc/remoteprocX/state
+
+To simulate a remote crash, execute:
+
+.. code-block::
+
+   echo 1 > /sys/kernel/debug/remoteproc/remoteprocX/crash
+
+To get the trace logs, execute
+
+.. code-block::
+
+   cat /sys/kernel/debug/remoteproc/remoteprocX/crashX
+
+where X will be 0 or 1 if there are 2 resources. Also, this
+file will only exist if resources are defined in ELF firmware
+file.
+
+The coredump feature can be disabled with the following command:
+
+.. code-block::
+
+   echo disabled > /sys/kernel/debug/remoteproc/remoteprocX/coredump
+
+Userspace can also control start/stop of rproc by using a
+remoteproc Character Device, it can open the open a file descriptor
+and write `start` to initiate it, and `stop` to terminate it.
+
+[FIXME -- better explanations]