Re: [RFC PATCH v1 1/4] rust: core abstractions for network PHY drivers

[Trevor Gross <tmgross@umich.edu>]

On Wed, Sep 13, 2023 at 11:05:31PM +0200, Andrew Lunn wrote:
> > [...]
> >
> > So by lifetime, it means while it is inside this function?
> >

Boqun covered this example quite well, here are some more general
crash course notes if it helps -

Lifetime is just rust lingo for compiler-tracked metadata on a
pointer, pointer + lifetime = reference (`&`). An example

    struct Foo<'a> {
        bar: &'a u32
    }

Read that as:
- a `Foo` will exist and be valid for some amount of time (of course)
- call the time it exists for `'a` [^1]
- `bar` is a pointer to something
- `bar` has lifetime `'a`. Which means, whatever `bar` points to must
  be valid for at least `'a`, i.e, at least as long as `Foo` is valid

Same rules you have to follow in any language, having these
annotations just tells the compiler about it. Then it keeps track and
makes sure they get followed. Functions give similar information:

    /// Return the first substring of `haystack` that starts with `needle`
    fn strstr<'a, 'b>(haystack: &'a str, needle: &'b str) -> &'a str;

The return value and `haystack` have the same lifetime, so you know
you can't `destroy` haystack as long as the return value is in use.
`needle` has a different lifetime so it's clear that it is unrelated.
In the original function

>> +    /// # Safety
>> +    ///
>> +    /// For the duration of the lifetime 'a, the pointer must be valid for writing and nobody else
>> +    /// may read or write to the `phy_device` object.
>> +    pub unsafe fn from_raw<'a>(ptr: *mut bindings::phy_device) -> &'a mut Self

A compiler-tracked lifetime is conjured from nothing, so the caller
gets to decide what that is (usually implicitly but can be specified).
This could be anything, hence "unsafe" and instructions on how to make
it correct. Once created, the compiler will track the above rules.

The other part of the picture is that rust strictly enforces one
`&mut` reference XOR any number `&` (const) references to a piece of
data at a time [^2]. The exception to this is of course things that
safely allow access behind a non-exclusive reference -

> In theory, the core will protect the phy_device structure
> using the phydev->lock mutex, although we might be missing a few [...]

- such as mutexes :). [^3] The original comment could probably add
something like "with the exception of mutex-protected fields" or a
mention about the callbacks.

Bit awkward at first, but it winds up being very nice to kick the
mental pointer-validity-chasing load to the compiler.

[^1]: could be called `'foo` `'buffer` or anything else,
      `'a' `'b` ... are common for simple things
[^2]: at a lower level `&mut` is basically C's `restrict`. Easier
      to use when the compiler checks it.
[^3]: these types use `UnsafeCell` to tell the compiler
      they allow this and not to emit `restrict`. `Opaque`
      in bindings also does this.