linux-kernel - [PATCH 5/7] Remoteproc: Documentation: add userspace api

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20241022213516.1756-6-yesanishhere@gmail.com>
Date: Tue, 22 Oct 2024 14:35:14 -0700
From: anish kumar <yesanishhere@...il.com>
To: ohad@...ery.com,
	bjorn.andersson@...aro.org,
	mathieu.poirier@...aro.org,
	corbet@....net
Cc: linux-remoteproc@...r.kernel.org,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	anish kumar <yesanishhere@...il.com>
Subject: [PATCH 5/7] Remoteproc: Documentation: add userspace api

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

Signed-off-by: anish kumar <yesanishhere@...il.com>
---
 Documentation/remoteproc/index.rst          |  2 +
 Documentation/remoteproc/remoteproc-api.rst | 75 +++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 Documentation/remoteproc/remoteproc-api.rst

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]
-- 
2.39.3 (Apple Git-146)