[PATCH] docs: rust: add "The Rust experiment" section

[PATCH] docs: rust: add "The Rust experiment" section

[Miguel Ojeda]

Clarify that the Rust experiment is still going on to avoid
confusion for both kernel maintainers and end users.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
Andrew: I did not add a `Suggested-by` just in case, but please let me know
if you want it, of course.

 Documentation/rust/index.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index e599be2cec9b..aaed36af15ce 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -6,6 +6,23 @@ Rust
 Documentation related to Rust within the kernel. To start using Rust
 in the kernel, please read the quick-start.rst guide.

+
+The Rust experiment
+-------------------
+
+The Rust support was merged in v6.1 into mainline in order to help in
+determining whether Rust as a language was suitable for the kernel, i.e. worth
+the tradeoffs.
+
+Currently, the Rust support is primarily intended for kernel developers and
+maintainers interested in the Rust support, so that they can start working on
+abstractions and drivers, as well as helping the development of infrastructure
+and tools.
+
+In particular, if you are an end user, please note that there are no in-tree
+drivers/modules suitable or intended for production use yet.
+
+
 .. only:: rustdoc and html

 	You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_.

base-commit: 94f6f0550c625fab1f373bb86a6669b45e9748b3
--
2.42.0

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Andrew Lunn]

On Wed, Oct 18, 2023 at 06:09:22PM +0200, Miguel Ojeda wrote:
> Clarify that the Rust experiment is still going on to avoid
> confusion for both kernel maintainers and end users.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
> Andrew: I did not add a `Suggested-by` just in case, but please let me know
> if you want it, of course.
> 
>  Documentation/rust/index.rst | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
> index e599be2cec9b..aaed36af15ce 100644
> --- a/Documentation/rust/index.rst
> +++ b/Documentation/rust/index.rst
> @@ -6,6 +6,23 @@ Rust
>  Documentation related to Rust within the kernel. To start using Rust
>  in the kernel, please read the quick-start.rst guide.
> 
> +
> +The Rust experiment
> +-------------------
> +
> +The Rust support was merged in v6.1 into mainline in order to help in
> +determining whether Rust as a language was suitable for the kernel, i.e. worth
> +the tradeoffs.
> +
> +Currently, the Rust support is primarily intended for kernel developers and
> +maintainers interested in the Rust support, so that they can start working on
> +abstractions and drivers, as well as helping the development of infrastructure
> +and tools.
> +
> +In particular, if you are an end user, please note that there are no in-tree
> +drivers/modules suitable or intended for production use yet.

It very unlikely end users read this document. And that statement is
not limited to end users, it is true for everybody.

What we should be saying is that Rust for the Linux kernel in general
is not ready for production use. Developing drivers in Rust is
currently for experimentation only. Given the experimental nature of
the work, there is some risk Rust will never be ready for production
use.

   Andrew

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Miguel Ojeda]

On Wed, Oct 18, 2023 at 6:27 PM Andrew Lunn <andrew@lunn.ch> wrote:
>
> It very unlikely end users read this document.

We can add a note to the Kconfig symbol too -- would that be OK with you?

> And that statement is
> not limited to end users, it is true for everybody.

Agreed, but that bit is meant to emphasize that end users do not have
a reason to use it at all (unlike kernel developers etc. from the
previous paragraph)

> What we should be saying is that Rust for the Linux kernel in general
> is not ready for production use. Developing drivers in Rust is
> currently for experimentation only. Given the experimental nature of
> the work, there is some risk Rust will never be ready for production
> use.

The risk is that Rust gets dropped from the kernel because it is not
used enough, not so much that there is a fundamental problem to solve
in order to reach production.

Cheers,
Miguel

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Miguel Ojeda]

On Wed, Oct 18, 2023 at 6:41 PM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> We can add a note to the Kconfig symbol too -- would that be OK with you?

Or do you mean you think the Quick Start guide would be a better place
given that is perhaps more likely to be read by end users that want to
just compile the kernel?

If so, I am happy to move it there.

Cheers,
Miguel

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Andrew Lunn]

On Wed, Oct 18, 2023 at 06:41:10PM +0200, Miguel Ojeda wrote:
> On Wed, Oct 18, 2023 at 6:27 PM Andrew Lunn <andrew@lunn.ch> wrote:
> >
> > It very unlikely end users read this document.
> 
> We can add a note to the Kconfig symbol too -- would that be OK with you?
> 
> > And that statement is
> > not limited to end users, it is true for everybody.
> 
> Agreed, but that bit is meant to emphasize that end users do not have
> a reason to use it at all (unlike kernel developers etc. from the
> previous paragraph)
> 
> > What we should be saying is that Rust for the Linux kernel in general
> > is not ready for production use. Developing drivers in Rust is
> > currently for experimentation only. Given the experimental nature of
> > the work, there is some risk Rust will never be ready for production
> > use.
> 
> The risk is that Rust gets dropped from the kernel because it is not
> used enough, not so much that there is a fundamental problem to solve
> in order to reach production.

I've talked to a small number of netdev developers, not many, but
some. The general impression i get is that it is unclear what
experimental actually means, and they have no idea what makes it not
production ready. The two are also not necessarily mutually exclusive.

To me, it appears Rust is not production ready because:

You need to disable module versioning.
You need to disable structure layout randomisation

On X86, you need to disable X86_KERNEL_IBT and RETHUNK, both of which
are part of the mitigation for speculative execution vulnerabilities

So no vendor is going to release a kernel with these disabled.

Networking also tends to be architecture independent, so production
features need to run on X86, ARM, ARM64, and to a lesser extent MIPS,
RISC-V, etc. I know this is documented, but it does not appear to be
that well known within the networking community.

Networking people also tend to be interested in endianness, does the
code work on big endian as well as little endian? Big endian is dying
out, but its not gone yet. However, with only x86 supported in
mainline today, it does not seem possible to test big endian. I assume
the rust type system will actually deal with this to a large extent?
But are developers writing abstractions which are sound with respect
to endianness?

I think it would be good to describe the experiment a bit. With a
multi year experiment, you often have short term goals and long term
goals.  What are these goals? What is the Rust for linux community
trying to prove in the next few kernel cycles? What do you consider to
be 4 or more cycles away? What do you consider not so important now
because its not needed for your short term goals? That might also help
developers understand when it will transition to production ready, but
still be experimental.

And you obviously need a disclaimer, Rust for Linux is a community,
developers are free to scratch their own itch, so things might happen
in a different order. And information like this might help get people
involved, helping solve some of the limitations, spur research into
different goals etc.

	Andrew

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Carlos Bilbao]

On 10/20/23 10:00, Andrew Lunn wrote:
> On Wed, Oct 18, 2023 at 06:41:10PM +0200, Miguel Ojeda wrote:
>> On Wed, Oct 18, 2023 at 6:27 PM Andrew Lunn <andrew@lunn.ch> wrote:
>>>
>>> It very unlikely end users read this document.
>>
>> We can add a note to the Kconfig symbol too -- would that be OK with you?
>>
>>> And that statement is
>>> not limited to end users, it is true for everybody.
>>
>> Agreed, but that bit is meant to emphasize that end users do not have
>> a reason to use it at all (unlike kernel developers etc. from the
>> previous paragraph)
>>
>>> What we should be saying is that Rust for the Linux kernel in general
>>> is not ready for production use. Developing drivers in Rust is
>>> currently for experimentation only. Given the experimental nature of
>>> the work, there is some risk Rust will never be ready for production
>>> use.
>>
>> The risk is that Rust gets dropped from the kernel because it is not
>> used enough, not so much that there is a fundamental problem to solve
>> in order to reach production.
> 
> I've talked to a small number of netdev developers, not many, but
> some. The general impression i get is that it is unclear what
> experimental actually means, and they have no idea what makes it not
> production ready. The two are also not necessarily mutually exclusive.
> 
> To me, it appears Rust is not production ready because:
> 
> You need to disable module versioning.
> You need to disable structure layout randomisation
> 
> On X86, you need to disable X86_KERNEL_IBT and RETHUNK, both of which
> are part of the mitigation for speculative execution vulnerabilities
> 
> So no vendor is going to release a kernel with these disabled.
> 
> Networking also tends to be architecture independent, so production
> features need to run on X86, ARM, ARM64, and to a lesser extent MIPS,
> RISC-V, etc. I know this is documented, but it does not appear to be
> that well known within the networking community.
> 
> Networking people also tend to be interested in endianness, does the
> code work on big endian as well as little endian? Big endian is dying
> out, but its not gone yet. However, with only x86 supported in
> mainline today, it does not seem possible to test big endian. I assume
> the rust type system will actually deal with this to a large extent?
> But are developers writing abstractions which are sound with respect
> to endianness?
> 
> I think it would be good to describe the experiment a bit. With a
> multi year experiment, you often have short term goals and long term
> goals.  What are these goals? What is the Rust for linux community
> trying to prove in the next few kernel cycles? What do you consider to
> be 4 or more cycles away? What do you consider not so important now
> because its not needed for your short term goals? That might also help
> developers understand when it will transition to production ready, but
> still be experimental.
> 
> And you obviously need a disclaimer, Rust for Linux is a community,
> developers are free to scratch their own itch, so things might happen
> in a different order. And information like this might help get people
> involved, helping solve some of the limitations, spur research into
> different goals etc.
> 

Points such as:

- Clarifying the definition of 'experimental' and why Rust is not yet
   considered production-ready.

- Providing insights into the short-term and long-term goals of the
   project.

- Addressing concerns related to endianness.

are indeed important aspects to consider, and documenting them would help.
But that's not what this commit is about, and the index page is the last
place to comment on such evolving topics.

> 	Andrew
> 

Thanks,
Carlos

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Miguel Ojeda]

On Fri, Oct 20, 2023 at 5:00 PM Andrew Lunn <andrew@lunn.ch> wrote:
>
> I've talked to a small number of netdev developers, not many, but
> some.

Thanks Andrew, this is valuable information (also for the upcoming
talk in netdevconf).

We have been putting some of the meta-information you mention in our
webpage instead, because it is easier to update (it is our `P:`
field). We will do our best to keep expanding it in the future.

Cheers,
Miguel

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Carlos Bilbao]

On 10/18/23 11:09, Miguel Ojeda wrote:
> Clarify that the Rust experiment is still going on to avoid
> confusion for both kernel maintainers and end users.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
> Andrew: I did not add a `Suggested-by` just in case, but please let me know
> if you want it, of course.
> 
>   Documentation/rust/index.rst | 17 +++++++++++++++++
>   1 file changed, 17 insertions(+)
> 
> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
> index e599be2cec9b..aaed36af15ce 100644
> --- a/Documentation/rust/index.rst
> +++ b/Documentation/rust/index.rst
> @@ -6,6 +6,23 @@ Rust
>   Documentation related to Rust within the kernel. To start using Rust
>   in the kernel, please read the quick-start.rst guide.
> 
> +
> +The Rust experiment
> +-------------------
> +
> +The Rust support was merged in v6.1 into mainline in order to help in
> +determining whether Rust as a language was suitable for the kernel, i.e. worth
> +the tradeoffs.
> +
> +Currently, the Rust support is primarily intended for kernel developers and
> +maintainers interested in the Rust support, so that they can start working on
> +abstractions and drivers, as well as helping the development of infrastructure
> +and tools.
> +
> +In particular, if you are an end user, please note that there are no in-tree
> +drivers/modules suitable or intended for production use yet.
> +

Personally, I would rephrase this to:

"Please note that, as an end user, there are currently no in-tree drivers
or modules suitable or intended for production use."

Also, I believe this should go here and not in Quick Start. The average end
user, to whom this sentence seems to refer, typically begins his/her
learning journey from the index page of our website.

I think this will be helpful.

Reviewed-by: Carlos Bilbao <carlos.bilbao@amd.com>

> +
>   .. only:: rustdoc and html
> 
>   	You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_.
> 
> base-commit: 94f6f0550c625fab1f373bb86a6669b45e9748b3
> --
> 2.42.0
> 

Thanks,
Carlos

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Miguel Ojeda]

On Mon, Oct 23, 2023 at 4:34 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> Personally, I would rephrase this to:
>
> "Please note that, as an end user, there are currently no in-tree drivers
> or modules suitable or intended for production use."

Yeah, I think the "yet" -> "currently" change helps, so I took it. I
haven't changed the "if" to "as" because some readers are not really
end users but kernel developers/maintainers, so I think it could be a
bit confusing.

> I think this will be helpful.
>
> Reviewed-by: Carlos Bilbao <carlos.bilbao@amd.com>

Thanks! I have changed the paragraph to this, can I still use your
`Reviewed-by`?

  If you are an end user, please note that there are currently no in-tree
  drivers/modules suitable or intended for production use, and that the Rust
  support is still in development/experimental, especially for certain kernel
  configurations.

Cheers,
Miguel

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Carlos Bilbao]

On 10/24/23 04:16, Miguel Ojeda wrote:
> On Mon, Oct 23, 2023 at 4:34 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>>
>> Personally, I would rephrase this to:
>>
>> "Please note that, as an end user, there are currently no in-tree drivers
>> or modules suitable or intended for production use."
> 
> Yeah, I think the "yet" -> "currently" change helps, so I took it. I
> haven't changed the "if" to "as" because some readers are not really
> end users but kernel developers/maintainers, so I think it could be a
> bit confusing.
> 
>> I think this will be helpful.
>>
>> Reviewed-by: Carlos Bilbao <carlos.bilbao@amd.com>
> 
> Thanks! I have changed the paragraph to this, can I still use your
> `Reviewed-by`?

Yes, that's perfect.

> 
>    If you are an end user, please note that there are currently no in-tree
>    drivers/modules suitable or intended for production use, and that the Rust
>    support is still in development/experimental, especially for certain kernel
>    configurations.
> 
> Cheers,
> Miguel

Thanks,
Carlos

Re: [PATCH] docs: rust: add "The Rust experiment" section

[Miguel Ojeda]

On Wed, Oct 18, 2023 at 6:09 PM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Clarify that the Rust experiment is still going on to avoid
> confusion for both kernel maintainers and end users.
>
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Applied to `rust-next`, with the new paragraph -- thanks everyone!

Cheers,
Miguel