linux-kernel - Re: [WIP RFC v2 33/35] WIP: rust: drm/kms: Add VblankSupport

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: <CANiq72=M3=0rcTfQS9Gch8NeNyrpXb91t-z-gDBSDO8V-Bh5gQ@mail.gmail.com>
Date: Tue, 14 Jan 2025 16:04:41 +0100
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Lyude Paul <lyude@...hat.com>, Daniel Almeida <daniel.almeida@...labora.com>, 
	dri-devel@...ts.freedesktop.org, rust-for-linux@...r.kernel.org, 
	Asahi Lina <lina@...hilina.net>, Danilo Krummrich <dakr@...nel.org>, mcanal@...lia.com, 
	airlied@...hat.com, zhiw@...dia.com, cjia@...dia.com, jhubbard@...dia.com, 
	Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, 
	Wedson Almeida Filho <wedsonaf@...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>, Andreas Hindborg <a.hindborg@...sung.com>, 
	Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>, 
	Danilo Krummrich <dakr@...hat.com>, Mika Westerberg <mika.westerberg@...ux.intel.com>, 
	open list <linux-kernel@...r.kernel.org>
Subject: Re: [WIP RFC v2 33/35] WIP: rust: drm/kms: Add VblankSupport

On Tue, Jan 14, 2025 at 3:24 PM Simona Vetter <simona.vetter@...ll.ch> wrote:
>
> Feels like trying to replicate docs in rust might be dangerous, because if
> we have to keep really detailed and nuanced docs around in two places we
> will fail.
>
> Imo would be better to just explain how this maps to the C side and link
> to that for full docs? Or somehow include that, but then all the
> hyperlinks need to work from the C side kerneldoc or it's again
> incomplete.

Yeah, if things would be duplicated (in a way that does not add much
value, e.g. things that do not require linking to many Rust-side
things or does not use the examples KUnit support etc.), then I would
say it is best to do it in a single place.

To do that, we already support the `srctree/` links that can point to
files (and in rust.docs.kernel.org get rendered to git.kernel.org). To
point to rendered docs instead of files, for the time being the best
so far is to link to docs.kernel.org directly.

Then, what I proposed to upstream Rust is to have a feature that would
give us a way to have a bibliography/map of links that could be used
similarly to the existing intradoc-links in Rust docs. That way,
projects could write something like [`struct my_struct`] and you would
automatically get a link to the suitable URL to the C item, or
something like [`ref:interleaved_replies`] to get a link to the
Documentation/ rST reference and so on. It would also help to have
common links without having to repeat them everywhere. With that in
place, we could replace the docs.kernel.org links (though that
requires rendering the docs, and we heard from at least someone that
didn't want that at all...).

Then we can also work on the other direction somehow, e.g. sharing a
way to render docs properly for both C and Rust. I would like to work
on some of that after the build system stuff.

Cheers,
Miguel