From: Roberto Sassu <roberto.sassu@xxxxxxxxxx>
Add a documentation, to explain the motivation behind the new component, to
describe the software architecture, the API and an example used for
testing.
Signed-off-by: Roberto Sassu <roberto.sassu@xxxxxxxxxx>
---
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/umd_mgmt.rst | 99 +++++++++++++++++++++++++++
MAINTAINERS | 1 +
3 files changed, 101 insertions(+)
create mode 100644 Documentation/driver-api/umd_mgmt.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index ff9aa1afdc6..ad42cd968dc 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -113,6 +113,7 @@ available subsections can be seen below.
xillybus
zorro
hte/index
+ umd_mgmt
.. only:: subproject and html
diff --git a/Documentation/driver-api/umd_mgmt.rst b/Documentation/driver-api/umd_mgmt.rst
new file mode 100644
index 00000000000..7dbb50b3643
--- /dev/null
+++ b/Documentation/driver-api/umd_mgmt.rst
@@ -0,0 +1,99 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+User Mode Driver Management Library
+===================================
+
+:Author: Roberto Sassu, Huawei Technologies Duesseldorf GmbH
+:Date: 2023-03-16
+
+Introduction
+============
+
+The idea of moving code away from the kernel and running it in user space
+is not new. For example, the User Space I/O driver model allows developers
+to implement most of the driver logic in user space, and keep only a small
+part in a kernel module, for example to handle interrupts.
+
+The User Mode Driver (UMD) is a more specialized solution, primarily used
+by bpfilter, consisting of a user space process running from code embedded
+in a kernel module, communicating only through a pipe with the kernel.
+
+The kernel makes a request, possibly originated by the user of the system,
+and sends it to the user space process. The latter handles the kernel
+request, and sends the response back to the kernel. Finally, the kernel
+eventually forwards the result to the user.
+
+This usage model is particularly interesting for security. The kernel can
+offload to user space workloads that could introduce possible threats, for
+example parsing unknown and possibly malicious data. While the kernel
+already does that, it is important to limit to the minimum the chances of
+an attacker to exploit a vulnerability in the kernel code.
+
+If a user space process becomes corrupted, it can still send malicious data
+to the kernel, but it won't be able to directly corrupt the kernel memory.
+In addition, if the communication protocol between the user space process
+and the kernel is simple enough, malicious data can be effectively
+sanitized.
+
+The purpose of this library is simply to facilitate developers to create
+UMDs and to help them customize the UMDs to their needs.
+
+
+
+Architecture
+============
+
+The architecture of the UMD library is as follows:
+
+::
+
+ +-----------+ +---------------+
+ | UMD | 2. request module | UMD Loader |
+ | Manager |------------------->| (kmod + |
+ | |------+ | user binary) |
+ +-----------+ | +---------------+
+ ^ | | kernel space
+ --------------------------------------------------------------------------
+ | | 4. send/ v 3. fork/execve/pipe user space
+ | | receive +-------------+
+ 1. user request +------------>| UMD Handler |
+ | (exec user |
+ | binary) |
+ +-------------+
+
+The `UMD Manager` is the frontend interface to any user or
+kernel-originated request. It invokes the `UMD Loader` to start the
+`UMD Handler`, and communicates with the latter to satisfy the request.
+
+The `UMD Loader` is merely responsible to extract the `user binary` from
+the kernel module, copy it to a tmpfs filesystem, fork the current process,
+start the `UMD Handler`, and create a pipe for the communication between
+the `UMD Manager` and the `UMD Handler`.
+
+The `UMD Handler` reads requests from the `UMD Manager`, processes them
+internally, and sends the response to it.
+
+
+API
+===
+
+.. kernel-doc:: include/linux/usermode_driver_mgmt.h
+
+.. kernel-doc:: kernel/usermode_driver_mgmt.c
+
+
+Example
+=======
+
+An example of usage of the UMD management library can be found in
+tools/testing/selftests/umd_mgmt/sample_umd.
+
+sample_mgr.c implements the `UMD Manager`, sample_loader.c implements the
+`UMD Loader` and, finally, sample_handler.c implements the `UMD Handler`.
+
+The `UMD Manager` exposes /sys/kernel/security/sample_umd and accepts a
+number between 0-128K intended as an offset in the response buffer, at
+which the `UMD Handler` sets the byte to 1. The `UMD Manager` verifies
+that. If the byte is not set to 1, the `UMD Manager` rejects the write, so
+that the failure can be reported by the test.
diff --git a/MAINTAINERS b/MAINTAINERS
index a0cd161843e..4b9d251259d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11249,6 +11249,7 @@ KERNEL USERMODE DRIVER MANAGEMENT
M: Roberto Sassu <roberto.sassu@xxxxxxxxxx>
L: linux-kernel@xxxxxxxxxxxxxxx
S: Maintained
+F: Documentation/driver-api/umd_mgmt.rst
F: include/linux/usermode_driver_mgmt.h
F: kernel/usermode_driver_mgmt.c
F: tools/testing/selftests/umd_mgmt/*
--
2.25.1
