From 6027745d002b574556d8199ddfa5d0736ab5752f Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Sat, 23 Sep 2023 18:45:46 +0200 Subject: [PATCH] Add "Out-of-tree modules" page In a recent discussion around a networking submission, it seemed that some extra clarifications about out-of-tree modules could be useful for developers looking to develop Rust code for the kernel [1]. Thus add an "Out-of-tree modules" page to clarify the focus of the Rust for Linux project, what is intended to be supported around out-of-tree code and what kinds of patches make sense to submit to the kernel mailing list. Importantly, add links to other pages from the mainline kernel documentation. Link: https://rust-for-linux.zulipchat.com/#narrow/stream/396592-Networking/topic/NAPI.20Abstractions/near/385885376 [1] Signed-off-by: Miguel Ojeda --- SUMMARY.md | 1 + src/Out-of-tree-modules.md | 13 +++++++++++++ 2 files changed, 14 insertions(+) create mode 100644 src/Out-of-tree-modules.md diff --git a/SUMMARY.md b/SUMMARY.md index 5fb5e87..d2b7253 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -9,6 +9,7 @@ - [Unstable features](Unstable-features.md) - [Backporting and stable/LTS releases](Backporting-and-stable-LTS-releases.md) - [Third-party crates](Third-party-crates.md) + - [Out-of-tree modules](Out-of-tree-modules.md) - [Industry and academia support](Industry-and-academia-support.md) - [Sponsors](Sponsors.md) diff --git a/src/Out-of-tree-modules.md b/src/Out-of-tree-modules.md new file mode 100644 index 0000000..4e53a5f --- /dev/null +++ b/src/Out-of-tree-modules.md @@ -0,0 +1,13 @@ +# Out-of-tree modules + +The Linux kernel supports [building out-of-tree modules](https://docs.kernel.org/kbuild/modules.html). Both C and Rust modules can be developed as out-of-tree ones, and we provide a [basic template](https://github.com/Rust-for-Linux/rust-out-of-tree-module) for an out-of-tree Linux kernel module written in Rust. + +However, please note that the Rust for Linux project is part of the kernel and has always focused its efforts towards getting code into the mainline kernel. + +In particular, this means that Rust [internal APIs can be changed at any time](https://docs.kernel.org/process/4.Coding.html#internal-api-changes), just like C ones, when the need arises. Similarly, code present at any point in our different [branches](Branches.md) is not intended to form a stable base for out-of-tree development. + +In addition, patches submitted to the mailing list should generally focus on in-tree development efforts. In particular, Rust abstractions submitted upstream require in-tree users. Abstractions intended for out-of-tree users cannot be merged. Even if those abstractions may be obviously useful for future in-tree users, there needs to be an agreed upon in-tree user. + +For these reasons and others, please consider [submitting](Contributing.md) your use cases upstream — see [the importance of getting code into the mainline](https://docs.kernel.org/process/1.Intro.html#the-importance-of-getting-code-into-the-mainline). + +Having said that, we understand that some module development is done out-of-tree and may not be possible to upstream. Even in those cases, if your company, organization or team has a use case for Rust, please [contact us](Contact.md), since it is important to highlight those use cases early on in order to showcase the [interest from industry and academia](Industry-and-academia-support.md) in Rust.