Add information about how userspace
can control the remoteproc framework
and different ways to do that.
Signed-off-by: anish kumar <yesanishhere@xxxxxxxxx>
---
Documentation/driver-api/remoteproc/index.rst | 1 +
.../driver-api/remoteproc/remoteproc-api.rst | 77 +++++++++++++++++++
2 files changed, 78 insertions(+)
create mode 100644 Documentation/driver-api/remoteproc/remoteproc-api.rst
diff --git a/Documentation/driver-api/remoteproc/index.rst b/Documentation/driver-api/remoteproc/index.rst
index 7fa1c5755be8..840b4672352b 100644
--- a/Documentation/driver-api/remoteproc/index.rst
+++ b/Documentation/driver-api/remoteproc/index.rst
@@ -20,6 +20,7 @@ Authors:
remoteproc
remoteproc-kernel-api
+ remoteproc-api
Mailing List
------------
diff --git a/Documentation/driver-api/remoteproc/remoteproc-api.rst b/Documentation/driver-api/remoteproc/remoteproc-api.rst
new file mode 100644
index 000000000000..0306b331a20e
--- /dev/null
+++ b/Documentation/driver-api/remoteproc/remoteproc-api.rst
@@ -0,0 +1,77 @@
+==================================
+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.
+
+.. code-block:: c
+
+ echo start > /sys/class/remoteproc/remoteprocX/state
+ echo stop > /sys/class/remoteproc/remoteprocX/state
+
+To know the state of rproc:
+
+.. code-block:: c
+
+ cat /sys/class/remoteproc/remoteprocX/state
+
+
+To dynamically replace firmware, execute the following commands:
+
+.. code-block:: c
+
+ 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:: c
+
+ echo 1 > /sys/kernel/debug/remoteproc/remoteprocX/crash
+
+To get the trace logs, execute
+
+.. code-block:: c
+
+ 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:: c
+
+ 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]
--
2.39.3 (Apple Git-146)
