From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-ej1-f46.google.com (mail-ej1-f46.google.com [209.85.218.46]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 029CA1BF328 for ; Tue, 14 Jan 2025 15:38:50 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.218.46 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736869132; cv=none; b=S0r9yKZrUoqhs8Bbsl2FLZDY/99BQZsG2WQZg1vKVEPy50JVLTM83wi24oRDVw99LYAQ6o2u4WxP3py6ET7GAC77x2LoUkoFDOkkUO2vs5L6QZdxhkQfZtwmf79Isr+R0V3+VWIyfImGDJF5pkc2qkXv0M23Wpe5FXm4FA6+sg4= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1736869132; c=relaxed/simple; bh=qWwRbalVlFVb5ebvQeyhAkWonrhpzXMr3MB2kUA1rHQ=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=kiDW8R4sdpiPFsoRS6mb7FZ9X9jc8dARGGpES2pCiQt07FRLz7BVKRqO6CgqwGYyw1tMCNfMjOK2cUkoXUo3z+cwkOMbwhVGwkB0E7DL/lZYUiFDKb7BEzdMXwdFriQ57sfaUUm+dNKO6sNz49gU/kEsTBbqnmmFESM+H+gkAmI= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=ffwll.ch; spf=none smtp.mailfrom=ffwll.ch; dkim=pass (1024-bit key) header.d=ffwll.ch header.i=@ffwll.ch header.b=SOGy2+D2; arc=none smtp.client-ip=209.85.218.46 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=ffwll.ch Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=ffwll.ch Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=ffwll.ch header.i=@ffwll.ch header.b="SOGy2+D2" Received: by mail-ej1-f46.google.com with SMTP id a640c23a62f3a-aaeec07b705so889742566b.2 for ; Tue, 14 Jan 2025 07:38:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; t=1736869129; x=1737473929; darn=vger.kernel.org; h=in-reply-to:content-transfer-encoding:content-disposition :mime-version:references:mail-followup-to:message-id:subject:cc:to :from:date:from:to:cc:subject:date:message-id:reply-to; bh=ODMaixCykybFpyXfXOh5SU/u+pXNOEmZVe97XLIWj0s=; b=SOGy2+D2mM9MHogYkRArEle3UYBbwch8TKIj4a0OXrEFzRjr4uHfB+ytOf7c/NkgoC vGlMhNs3iWkJE7Noeha7dvy23sN1TK2a24sL7bxdTZaoDaUEZbZe69C+ltsnh5bKmz4i Xf1B7qoenamgL21nHncTBOQC6ah9u5tmCfIf0= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736869129; x=1737473929; h=in-reply-to:content-transfer-encoding:content-disposition :mime-version:references:mail-followup-to:message-id:subject:cc:to :from:date:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=ODMaixCykybFpyXfXOh5SU/u+pXNOEmZVe97XLIWj0s=; b=drmA9CSCWhOSbEo65UYGLDGlKQneeLfaZHSXjktwxerA6TCKtFHG6ysKBQUOSRVWCb VQ/y/W/Cj5OEmneY6FP3nYdYZ82TlL8tKKuosAuGvGYSeYYWYwhDiqYo28WMKiNLPGgI fat51uNckk8d/qsf/5owIWyi9+0UUIfy7uTKFt6vKSYV70d99zk7C0C46Nkr1EAJptq9 SHtep0L2x5SZSq+5dfjrgaW1gn4xY2fCXs4Bt3a/uG4gEfxyr3xBn7siWTfMevMYu0xs /Ofa5AX6QIzrANy21lk4aH32p57Jo7UzNZNSornL6M1tWqkT10643MLst6yEquWU37yf rKAg== X-Forwarded-Encrypted: i=1; AJvYcCWJx6Lvk21BGOkdfrIq4vZF2LK1m7tMcxMRiJWHNAJb10wVlrBBagDNqkXN9AxTCULDXte1Txg6Z5HAZ1M=@vger.kernel.org X-Gm-Message-State: AOJu0Yydgcv71e1t/qHqRllhchzPrCAbykRXOOwhAXikQ3tfzcRFkVjV hJITtS2Ogfn2ttKStK6zUvg7ltcKLEbHh6zr+o8h6vlm/T2b4kFcDbSq+4jwaPo= X-Gm-Gg: ASbGncvbW/PkDydhYiTQ36e9OwauRSAqKEfda1D2SuVjx9R10GubTieXPPzQ4bf02Cv PguAZ0JEfdrQptX0S7+WY2adf+JKaIp4EAUnKIRwMZhkC4hY4QvDtA+s7cAQlfTBa/IOudiM/zo dJwE4KrgYqB85GShmLkjyDtC+/S5LZJxZXcJvIwgUI7TfNsJYZ0za9jFNnOs2Meiuqg4um7F9G0 zarB/+Vf3I5ShCJfLRrSWSS1KR7C68XF4DzmOd7138tjx3SUww8gpsfKZf9ETi1xQBJ X-Google-Smtp-Source: AGHT+IFKC0qtMfswjkUHdUbLXJ8Fzz/7FK60lz5r/sV1+p/qljFpLildKmIql5dlVsd79+eSBlA+SA== X-Received: by 2002:a17:907:3e9f:b0:aae:bd4c:22c0 with SMTP id a640c23a62f3a-ab2ab70aeccmr2271121566b.19.1736869129214; Tue, 14 Jan 2025 07:38:49 -0800 (PST) Received: from phenom.ffwll.local ([2a02:168:57f4:0:5485:d4b2:c087:b497]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-ab2c905cd8asm641773166b.7.2025.01.14.07.38.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 14 Jan 2025 07:38:48 -0800 (PST) Date: Tue, 14 Jan 2025 16:38:46 +0100 From: Simona Vetter To: Miguel Ojeda Cc: Lyude Paul , Daniel Almeida , dri-devel@lists.freedesktop.org, rust-for-linux@vger.kernel.org, Asahi Lina , Danilo Krummrich , mcanal@igalia.com, airlied@redhat.com, zhiw@nvidia.com, cjia@nvidia.com, jhubbard@nvidia.com, Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?iso-8859-1?Q?Bj=F6rn?= Roy Baron , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross , Danilo Krummrich , Mika Westerberg , open list Subject: Re: [WIP RFC v2 33/35] WIP: rust: drm/kms: Add VblankSupport Message-ID: Mail-Followup-To: Miguel Ojeda , Lyude Paul , Daniel Almeida , dri-devel@lists.freedesktop.org, rust-for-linux@vger.kernel.org, Asahi Lina , Danilo Krummrich , mcanal@igalia.com, airlied@redhat.com, zhiw@nvidia.com, cjia@nvidia.com, jhubbard@nvidia.com, Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?iso-8859-1?Q?Bj=F6rn?= Roy Baron , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross , Danilo Krummrich , Mika Westerberg , open list References: <20240930233257.1189730-1-lyude@redhat.com> <20240930233257.1189730-34-lyude@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: X-Operating-System: Linux phenom 6.12.3-amd64 On Tue, Jan 14, 2025 at 04:04:41PM +0100, Miguel Ojeda wrote: > On Tue, Jan 14, 2025 at 3:24 PM Simona Vetter 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...). Yeah I think something like [`struct my_struct`] in the rust doc to link to the C side would be best. Dropping full url is kinda nasty, because it also makes navigating the source code itself harder. And I fairly often read the kerneldoc in the sources itself, not the rendered form. But that's maybe more a developer/maintainer use-case, since generally when I read docs it's to make sure they still match the code, so best when that's all close together. > 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. Hm I guess the other direction might apply for when we implement helpers in rust that C drivers are expected to use, like the qr code generator we now have. I think at least medium term most of our referencing needs will go from rustdoc to kerneldoc though, and not the other direction. -Sima -- Simona Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch