linux-kernel - Re: [PATCH 3/3] rust: dma: add as_slice/write functions for CoherentAllocation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CANiq72mwp6=6PHzwaenovuJ+emW+A-wmun34oTUJQFd3vPV_zA@mail.gmail.com>
Date: Fri, 28 Mar 2025 00:38:57 +0100
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Abdiel Janulgue <abdiel.janulgue@...il.com>
Cc: a.hindborg@...nel.org, ojeda@...nel.org, 
	Danilo Krummrich <dakr@...nel.org>, Daniel Almeida <daniel.almeida@...labora.com>, 
	Robin Murphy <robin.murphy@....com>, Alex Gaynor <alex.gaynor@...il.com>, 
	Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, 
	Björn Roy Baron <bjorn3_gh@...tonmail.com>, 
	Benno Lossin <benno.lossin@...ton.me>, Alice Ryhl <aliceryhl@...gle.com>, 
	Trevor Gross <tmgross@...ch.edu>, 
	"open list:DMA MAPPING HELPERS DEVICE DRIVER API [RUST]" <rust-for-linux@...r.kernel.org>, 
	Marek Szyprowski <m.szyprowski@...sung.com>, 
	"open list:DMA MAPPING HELPERS" <iommu@...ts.linux.dev>, open list <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH 3/3] rust: dma: add as_slice/write functions for CoherentAllocation

Few doc nits...

On Wed, Mar 26, 2025 at 9:13 PM Abdiel Janulgue
<abdiel.janulgue@...il.com> wrote:
>
> +    /// Due to the safety requirements of slice, the caller should consider that the region could

Which requirements in particular? Link?

> +    /// be modified by the device at anytime. For ringbuffer type of r/w access or use-cases where

at anytime -> "at any time" or "anytime"

> +    /// the pointer to the live data is needed, `start_ptr()` or `start_ptr_mut()` could be

Intra-doc links where possible.

> +    /// Writes data to the region starting from `offset`. `offset` is in units of `T`, not the
> +    /// number of bytes.

I would double-check how it looks in the rendered docs (same for the
other method) -- the second sentence may be best in another paragraph,
i.e. outside the title, since it is special in the rendered
documentation ("short description"), unless you want to e.g.
differentiate from another variant.

> +        // SAFETY:
> +        // - The pointer is valid due to type invariant on `CoherentAllocation`
> +        // and we've just checked that the range and index is within bounds.

Please indent the comments as you would the docs -- the docs ones are
correct, and Clippy should check those, but it doesn't check normal
comments, sadly.

Thanks!

Cheers,
Miguel