Re: [PATCH v10 7/8] rust: Add read_poll_timeout functions

[Daniel Almeida <daniel.almeida@collabora.com>]

Sorry, ended up replying privately by mistake, resending with everybody else on cc:

——————


> On 14 Feb 2025, at 01:13, FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:
> 
> On Fri, 7 Feb 2025 22:50:37 -0300
> Daniel Almeida <daniel.almeida@collabora.com> wrote:
> 
>>> +/// Polls periodically until a condition is met or a timeout is reached.
>>> +///
>>> +/// ```rust
>>> +/// use kernel::io::poll::read_poll_timeout;
>>> +/// use kernel::time::Delta;
>>> +/// use kernel::sync::{SpinLock, new_spinlock};
>>> +///
>>> +/// let lock = KBox::pin_init(new_spinlock!(()), kernel::alloc::flags::GFP_KERNEL)?;
>>> +/// let g = lock.lock();
>>> +/// read_poll_timeout(|| Ok(()), |()| true, Delta::from_micros(42), Some(Delta::from_micros(42)));
>>> +/// drop(g);
>>> +///
>>> +/// # Ok::<(), Error>(())
>> 
>> IMHO, the example section here needs to be improved.
> 
> Do you have any specific ideas?
> 
> Generally, this function is used to wait for the hardware to be
> ready. So I can't think of a nice example.

Just pretend that you’re polling some mmio address that indicates whether some hardware
block is ready, for example.

You can use “ignore” if you want, the example just has to illustrate how this function works, really.

Something like

```ignore
 /* R is a fictional type that abstracts a memory-mapped register where `read()` returns Result<u32> */
 fn wait_for_hardware(ready_register: R) {
     let op = || ready_register.read()?

     // `READY` is some device-specific constant that we are waiting for.
     let cond =  |value: &u32| { *value == READY }

     let res = io::poll::read_poll_timeout (/* fill this with the right arguments */);

     /* show how `res` works, is -ETIMEDOUT returned on Err? */

     match res {
       Ok(<what is here?>) => { /* hardware is ready */}
       Err(e) => { /* explain that *value != READY here? */ }

     /* sleep is Option<Delta>, how does this work? i.e.: show both None, and Some(…) with some comments. */
 } 
```

That’s just a rough draft, but I think it's going to be helpful for users.

— Daniel