From:   Roberto Sassu <roberto.sassu@huaweicloud.com>
To:     corbet@lwn.net, ast@kernel.org, daniel@iogearbox.net,
        andrii@kernel.org, martin.lau@linux.dev, song@kernel.org,
        yhs@fb.com, john.fastabend@gmail.com, kpsingh@kernel.org,
        sdf@google.com, haoluo@google.com, jolsa@kernel.org,
        davem@davemloft.net, edumazet@google.com, kuba@kernel.org,
        pabeni@redhat.com, dsahern@kernel.org, shuah@kernel.org,
        brauner@kernel.org
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        bpf@vger.kernel.org, netdev@vger.kernel.org,
        linux-kselftest@vger.kernel.org, ebiederm@xmission.com,
        mcgrof@kernel.org, Roberto Sassu <roberto.sassu@huawei.com>
Subject: [PATCH 5/5] doc: Add documentation for the User Mode Driver management library
Date:   Fri, 17 Mar 2023 15:52:40 +0100
Message-Id: <20230317145240.363908-6-roberto.sassu@huaweicloud.com>
In-Reply-To: <20230317145240.363908-1-roberto.sassu@huaweicloud.com>
References: <20230317145240.363908-1-roberto.sassu@huaweicloud.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

From: Roberto Sassu <roberto.sassu@huawei.com>

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@huawei.com>
---
 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@huawei.com>
 L:	linux-kernel@vger.kernel.org
 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